docs: reconcile documentation with actual compiler behavior

Author: yeongseon

README.md

@@ -28,12 +28,13 @@ Before writing any code, understand the dialect's capabilities and limits:
 | Schema inspection (tables, columns) | ✅ |
 | IN, BETWEEN, LIKE operators | ✅ |
 | DISTINCT | ✅ |
+| DISTINCT with JOIN | ❌ |
 | GROUP BY / HAVING | ✅ |
 | Aggregate functions (COUNT, SUM, AVG, MIN, MAX) | ✅ |
-| Subqueries in WHERE ... IN | ✅ (non-correlated only) |
-| INNER / LEFT / RIGHT JOIN (equality ON) | ✅ (constrained) |
+| Subqueries in WHERE ... IN | ✅ (non-correlated only; no JOIN in outer/subquery) |
+| INNER / LEFT / RIGHT / FULL OUTER JOIN (equality ON) | ✅ (constrained) |
+| CROSS JOIN | ✅ |
 | Chained JOINs (3+ tables) | ✅ (constrained) |
-| **FULL OUTER JOIN** | ❌ |
 | CTEs | ❌ |
 | UNION / UNION ALL / INTERSECT / EXCEPT | ✅ |
 | **Window functions (OVER)** | ❌ |

docs/ROADMAP.md

@@ -1,91 +1,56 @@
 # Project Roadmap
 
-> **Current version**: 0.4.0 · **Python**: 3.10+ · **Published**: [PyPI](https://pypi.org/project/sqlalchemy-excel/)
+> **Current version**: 0.5.4 · **Python**: 3.10+ · **Published**: [PyPI](https://pypi.org/project/sqlalchemy-excel/)
 
 ## Completed
 
-### v0.1.0 — Initial Release
+### Core SQL and ORM surface
 
-- SQLAlchemy 2.0 dialect implementation
-- ORM support with `DeclarativeBase`
-- Basic SQL: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE
-- WHERE clauses with comparison operators
-- ORDER BY and LIMIT
-- Type mapping for common SQLAlchemy types
-- Schema inspection (`get_table_names`, `get_columns`, `has_table`)
+- SQLAlchemy 2.x dialect implementation for local Excel files
+- ORM support with `DeclarativeBase`, `Session`, and mapper reflection paths used in tests
+- CRUD support: `SELECT`, `INSERT`, `UPDATE`, `DELETE`
+- DDL support: `CREATE TABLE`, `DROP TABLE`
+- Multi-row `INSERT ... VALUES` and `INSERT ... SELECT`
+- Inspector support: `get_table_names`, `get_columns`, `has_table`
 
-### v0.2.x — Dialect Rewrite & Quality
+### Query capabilities available today
 
-- Complete dialect architecture rewrite: `ExcelCompiler`, `ExcelDDLCompiler`, `ExcelTypeCompiler`
-- Enhanced operators: IN, BETWEEN, LIKE
-- Codecov integration for coverage tracking
-- mypy strict mode with full type safety
-- PyPI Trusted Publisher (OIDC) for secure releases
-- GitHub Actions CI/CD pipeline
+- Filtering/operators: `IN`, `BETWEEN`, `LIKE`
+- Aggregation: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`
+- `GROUP BY` and `HAVING`
+- `DISTINCT` (single-table queries)
+- Non-correlated subqueries in `WHERE ... IN` (for `SELECT`, `UPDATE`, `DELETE`)
+- Join surface: `INNER`, `LEFT`, `RIGHT` shape, `FULL OUTER`, `CROSS`, chained joins
+- Compound queries: `UNION`, `UNION ALL`, `INTERSECT`, `EXCEPT`
+- `CASE WHEN` expressions and arithmetic expressions
+- UPSERT via `ON CONFLICT DO NOTHING / DO UPDATE`
 
-### v0.3.x — Graph API & Remote Excel
+### Platform and quality
 
-- `ExcelGraphDialect` for remote Excel files via Microsoft Graph API
-- `excel+graph:///drive_id/item_id` URL scheme
-- Entry point `excel.graph` for SQLAlchemy dialect resolution
-- Optional dependency: `pip install sqlalchemy-excel[graph]`
-- URL percent-decoding for drive/item IDs with special characters
-- `readonly` query parameter forwarding to Graph backend
-- `supports_statement_cache = False` on both dialects
+- `ExcelGraphDialect` for Microsoft Graph-backed workbooks (`excel+graph:///drive_id/item_id`)
+- Strict mypy, ruff linting/formatting, and CI on supported Python versions
+- High test coverage across compiler, dialect, ORM, DML/DDL, reflection, and end-to-end flows
 
-### v0.4.0 — Stabilization (Current)
+## In Progress / Next
 
-- HAVING guard via `_compose_select_body` override (compile-time error instead of silent ignore)
-- End-to-end tests: CRUD round-trip, ORM Session, inspector reflection, DDL lifecycle, rollback no-op
-- Compiler guard tests for all unsupported SQL features
-- Type compiler full coverage tests
-- Reflection edge case tests
-- Test coverage: **98% (117 tests)**
-- README restructured: limitations-first layout, Graph API moved to experimental section
+- Expand documentation examples for advanced query shapes and ORM patterns
+- Continue hardening edge cases around SQLAlchemy compilation and parser interoperability
+- Improve release notes and compatibility guidance as excel-dbapi evolves
 
-## Future
+## Not Planned
 
-### Planned
+- Full ACID transactions
+- Concurrent multi-writer semantics
+- `ALTER TABLE` / schema migration primitives
+- Foreign key enforcement and index management
+- Stored procedures and triggers
 
-- **DISTINCT**: Remove duplicate rows
-- **OFFSET**: Pagination support (currently only LIMIT works)
-- **Aggregate functions**: COUNT, SUM, AVG, MIN, MAX
-- **GROUP BY**: Grouping with aggregate functions
-- **Subqueries**: Nested SELECT statements
-- **Multi-sheet JOIN**: INNER JOIN, LEFT JOIN across sheets
-- **Async dialect**: `excel+aio://` with AsyncEngine support
-
-> These features require changes in the underlying [excel-dbapi](https://github.com/yeongseon/excel-dbapi) query engine.
-
-### Not Planned
-
-These are explicitly out of scope:
-
-- Full ACID transactions (Excel files don't support them)
-- Concurrent write support (single-writer model by design)
-- ALTER TABLE / schema migration
-- Foreign key enforcement or index support
-- Stored procedures or triggers
+These constraints are inherited from the Excel file model and underlying driver behavior.
 
 ## Long-Term Vision
 
-1. **Seamless SQLAlchemy experience** for Excel files
-2. **Analysts and developers** use familiar SQL/ORM tools with Excel
-3. **Bridge** ad-hoc Excel data and structured database workflows
-4. **Cloud-native Excel** via Microsoft Graph API (experimental)
-
-**Not a goal**: Replace real databases for production workloads.
-
-## Versioning
-
-sqlalchemy-excel follows [Semantic Versioning](https://semver.org/):
-
-- **PATCH** (0.x.**y**): Bug fixes
-- **MINOR** (0.**x**.0): New features, backward-compatible
-- **MAJOR** (**x**.0.0): Breaking changes, stable API
-
-**Current status**: Beta (0.x.x) — API may change before 1.0.0.
-
----
+1. Keep SQLAlchemy usage intuitive for spreadsheet-backed data workflows.
+2. Maintain compatibility with excel-dbapi capabilities as they expand.
+3. Provide clear boundaries so teams can choose Excel vs. traditional databases intentionally.
 
-See [CHANGELOG.md](../CHANGELOG.md) for detailed release history.
+See [CHANGELOG.md](../CHANGELOG.md) for release-by-release details.

docs/USAGE.md

@@ -149,10 +149,10 @@ with Session(engine) as session:
     users = session.scalars(stmt).all()
 ```
 
-### JOINs (including chained and RIGHT-join shape)
+### JOINs (including chained, RIGHT-join shape, FULL OUTER, and CROSS)
 
 ```python
-from sqlalchemy import Column, Integer, MetaData, String, Table, select
+from sqlalchemy import Column, Integer, MetaData, String, Table, select, true
 
 metadata = MetaData()
 users = Table(
@@ -185,6 +185,14 @@ stmt = (
 right_join_shape = select(orders.c.id, users.c.name).select_from(
     orders.join(users, users.c.id == orders.c.user_id, isouter=True)
 )
+
+# FULL OUTER JOIN
+full_outer = select(users.c.name, orders.c.id).select_from(
+    users.join(orders, users.c.id == orders.c.user_id, full=True)
+)
+
+# CROSS JOIN
+cross_join = select(users.c.id, orders.c.id).select_from(users.join(orders, true()))
 ```
 
 ### Compound Set Operations (UNION / INTERSECT / EXCEPT)
@@ -330,7 +338,7 @@ sqlalchemy-excel maps SQLAlchemy types to Excel storage types:
 
 sqlalchemy-excel has some limitations due to the nature of Excel as a database:
 
-- **Constrained JOIN support**: INNER/LEFT/RIGHT join shapes and chained joins are supported with equality ON clauses (`t1.col = t2.col`). FULL OUTER JOIN, OR/non-equality ON clauses, and non-column operands are rejected.
+- **Constrained JOIN support**: INNER/LEFT/RIGHT/FULL OUTER join shapes, CROSS JOIN, and chained joins are supported. `ON` clauses are limited to equality comparisons between columns from different join sources (`t1.col = t2.col`, `AND`-combined).
 - **Non-correlated subqueries only**: Subqueries supported in `WHERE ... IN (SELECT ...)` for SELECT, UPDATE, and DELETE. No correlated or nested subqueries.
 - **No CTEs**: CTE queries are not supported.
 - **No window functions**: `OVER` clause raises `CompileError`.