Skip to content

Commit 69189e0

Browse files
committed
Document spec coverage, refactoring, and verification limits
1 parent ea9382e commit 69189e0

5 files changed

Lines changed: 73 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ DB.fetch('SELECT active, created_at FROM items').with_libsql_types(
104104
).all
105105

106106
# Supported hints: :boolean, :date, :datetime, :timestamp, :time, :decimal,
107-
# :blob, or a callable. NULL always remains nil.
107+
# :integer, :float, :blob, or a callable. NULL always remains nil.
108108
DB.fetch('SELECT upper(name) AS label FROM items').with_libsql_types(
109109
label: ->(value) { value.freeze }
110110
).all
@@ -116,12 +116,16 @@ Use `Sequel::Model` normally for single-table model datasets. Joined/eager-graph
116116

117117
```sh
118118
bundle install
119+
bundle exec rake check # syntax, visibility, and warning-enabled tests
120+
bundle exec rake lint # syntax and method visibility only
119121
bundle exec rake test # real native local/file databases
120122
bundle exec rake upstream # upstream SQLite + integration specs
121123
bundle exec rake remote_local # real native HTTP client, local Hrana server
122124
```
123125

124-
The latter two commands need the ignored reference checkouts; setup instructions are in [development.md](docs/development.md). `tmp/` and `private_docs/` are Git-ignored and excluded from gem packaging. `private_docs/CONTINUATION.md` is the local continuation checkpoint to read after agent compaction.
126+
`upstream` and `remote_local` need the ignored reference checkouts; setup instructions are in [development.md](docs/development.md). `rake` defaults to `check`. Checks follow Sequel's own syntax/warnings/visibility approach; Sequel does not configure RuboCop or a complexity analyzer. See [the spec and code-quality review](docs/testing-review.md).
127+
128+
`tmp/` and `private_docs/` are Git-ignored and excluded from gem packaging. `private_docs/CONTINUATION.md` is the local continuation checkpoint to read after agent compaction.
125129

126130
For an explicit test against a **disposable** hosted database, set `LIBSQL_TEST_URL` and `LIBSQL_TEST_AUTH_TOKEN` in your environment, then run `bundle exec rake remote`. It creates randomly named test tables and drops those tables afterward. Hosted authentication, TLS, and embedded replication have not been validated in this workspace.
127131

‎docs/architecture.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@ The adapter follows Sequel's small Database/Dataset adapter pattern and delegate
88
| `lib/sequel/libsql/configuration.rb` | Normalize memory/file/remote/replica options, reject unsupported or conflicting configuration |
99
| `lib/sequel/libsql/connection.rb` | Own database/connection handles; scope statements, results, and rows with `ensure` |
1010
| `lib/sequel/libsql/native.rb` | Use the driver's native library/ABI; correct error, string, blob, and signed-integer handling |
11-
| `lib/sequel/libsql/dataset.rb` | Map native rows to Sequel hashes, bind query parameters, quote text, apply known result types |
11+
| `lib/sequel/libsql/dataset.rb` | Map native rows to Sequel hashes, bind query parameters, and quote text |
12+
| `lib/sequel/libsql/result_types.rb` | Resolve column origins and explicit type hints; reject ambiguous inference |
13+
| `lib/sequel/libsql/type_converter.rb` | Convert storage values to semantic SQLite types |
1214

1315
## Ownership and concurrency
1416

@@ -28,6 +30,10 @@ Sequel's unnumbered argument mapper generates `?` placeholders and orders/repeat
2830

2931
The C API exposes runtime types and column names, but not column declarations/origins. General sqlite3-style automatic result conversion is therefore impossible without a new upstream API. This adapter resolves only known single-table column projections, consulting Sequel's schema cache after the SQL has successfully prepared. It leaves expressions and ambiguous projections unchanged and offers `with_libsql_types` for explicit conversions.
3032

33+
Sequel's cached placeholder literalizer optimization is disabled because it replaces projected columns with opaque arguments. Without native declared-type metadata, that made repeated `get` calls lose their conversions after the cache activated. Native bound variables and named prepared statements remain supported; the tradeoff is additional Ruby SQL generation work.
34+
35+
Numeric timestamps follow Sequel's SQLite convention: Integer means Unix seconds and Float means Julian day. Numeric TIME values preserve microseconds. BLOB columns containing integer/real/text storage values convert through their string representation, and nonnumeric text in a decimal column remains text, matching Sequel's SQLite adapter.
36+
3137
Sequel invalidates its own schema cache for schema DSL changes. External schema changes and arbitrary DDL via `run` follow Sequel's usual cache rules; reload the affected schema or reconnect the Database object when needed. No extra unbounded type cache is introduced.
3238

3339
## Driver boundary

‎docs/compatibility.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ As of 2026-10-31, Apple Silicon macOS, Ruby 4.0.5, `turso_libsql` 0.2.0, bundled
66

77
- Native local/file tests cover CRUD, signed integer boundaries, UTF-8, arbitrary/empty blobs, invalid input, native lifetime cleanup, prepared queries, constraints, transactions/savepoints/commit failure, models, associations, migrations, schema alteration, pool concurrency, reconnect, and type hints.
88
- The same project suite passes with Sequel 5.80.0 and 5.109.0.
9-
- Sequel upstream at `75b425dd1c1f34908426dd70371d14e4afb9c933`: SQLite adapter plus all integration specs pass, with six upstream skips. The test sources are unmodified.
10-
- Real native HTTP execution against the official Hrana v3 Python fixture covers prepared Unicode/blob values, affected counts, inserted IDs, constraints, transactions/savepoints, reconnect, schema metadata, and RETURNING.
9+
- Sequel upstream at `75b425dd1c1f34908426dd70371d14e4afb9c933`: SQLite adapter plus integration run passes (901 tests, six upstream skips). The test sources are unmodified. Some additional groups are never defined for an external adapter: seven SQLite type-conversion cases gated on `adapter_scheme == :sqlite` now have local equivalents. See [the coverage review](testing-review.md).
10+
- Real native HTTP execution against the official Hrana v3 Python fixture covers prepared Unicode/blob values, affected counts, inserted IDs, constraints, transactions/savepoints, reconnect, schema metadata, empty results, NULL values, models using prepared statements, and INSERT/UPDATE/DELETE RETURNING.
1111
- The fixture wrapper only normalizes padded/unpadded base64 between Python and Rust. SQL and stream handling stay upstream. This is a protocol integration test, not a hosted Turso test.
1212

1313
Exact counts and commands are recorded in the local ignored continuation notes and test logs.

‎docs/development.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,22 @@
22

33
```sh
44
bundle install
5-
bundle exec rake test
5+
bundle exec rake check
66
```
77

88
Tests use real native libSQL databases and clean up temporary files. No network service or credentials are required for the default suite. `sqlite3` is a development dependency for upstream compatibility tests; it is not loaded by the adapter.
99

10+
## Code checks
11+
12+
`rake` defaults to `check`: `lint` followed by the tests. As in Sequel, tests run with `-w` and, on Ruby 3.4+, `-W:strict_unused_block`. There is no RuboCop/Standard configuration or complexity analyzer in Sequel's repository.
13+
14+
- `bundle exec rake check_syntax` checks Ruby syntax and parser warnings in project library, test, task, and example files, plus Gemfile/Rakefile/gemspec. It fails on invalid syntax or warnings. Ignored clones, private notes, and installed gems are outside its file list.
15+
- `bundle exec rake check_visibility` uses Jeremy Evans' `visibility_checker`, also used by Sequel's optional visibility checks. It checks the database, dataset, and prepared dataset; changes originating in the adapter fail the task. Preexisting visibility changes inside Sequel itself are excluded.
16+
- `bundle exec rake lint` runs both checks.
17+
- `.github/workflows/ci.yml` runs `rake check` on Linux with Ruby 3.3, 3.4, and 4.0. The workflow configuration has been validated locally; those hosted jobs have not yet run for these changes.
18+
19+
Code size was reviewed using Ruby's Prism AST to locate complete methods. No artificial complexity score is enforced. The largest configuration/type-inference methods were split by responsibility; see [testing-review.md](testing-review.md) for the measured sizes and coverage findings.
20+
1021
## Reference sources
1122

1223
Reference repositories are checked out under Git-ignored `tmp/upstream/`. The adapter does not load implementation code from them.

‎docs/testing-review.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Spec and code-quality review
2+
3+
Reviewed 2026-10-31 against the cloned upstream sources, after the initial adapter commit `0b966b1` was pushed.
4+
5+
## Upstream comparison
6+
7+
| Source | Existing coverage | Action here |
8+
| --- | --- | --- |
9+
| Sequel SQLite adapter + integration specs | SQL generation, schema changes, constraints, transactions, models, associations, migrations, prepared queries | Continue running unmodified upstream specs with `rake upstream` |
10+
| Sequel SQLite type-conversion group | Seven cases defined only for `adapter_scheme == :sqlite`; absent from the external-adapter run | Added local equivalents in `test/sqlite_types_test.rb` |
11+
| Sequel SQLite-specific URI, regexp, temporary-release groups | Target sqlite3-specific APIs or explicitly create `Sequel.sqlite` | Keep native libSQL URL tests and explicit rejection of unsupported regexp options; do not pretend these groups exercise this adapter |
12+
| libsql-activerecord | No dedicated adapter spec directory or test CI; example Rails scaffold has controller/system CRUD tests and an empty model test | Existing model tests cover local CRUD; added remote model lifecycle with Sequel's prepared-statements plugin |
13+
| libsql-activerecord execution code | Separates row-returning queries, batch execution, affected counts, and insert IDs | Added remote empty-result metadata, NULL values, and UPDATE/DELETE RETURNING cases |
14+
15+
The ActiveRecord adapter cannot be tested by loading its Rails scaffold into this project: that would exercise ActiveRecord's adapter, not the Sequel implementation.
16+
17+
## Bugs exposed by the new specs
18+
19+
- Integer and Float timestamps now use Unix seconds and Julian days, respectively, supporting both Time and DateTime output classes.
20+
- Numeric TIME values now round fractional seconds to microseconds as Sequel does.
21+
- Numeric/text storage values in a BLOB column now become `Sequel::SQL::Blob` rather than raising or remaining plain strings.
22+
- Nonnumeric text in a decimal column remains text, consistent with SQLite's flexible storage and Sequel's converter.
23+
- Repeated `get` calls no longer lose result types once Sequel's placeholder-literalizer cache activates. The adapter disables that optimization because it hides projection origins; native bound/prepared statements still work.
24+
25+
## Linting and size review
26+
27+
Sequel has no RuboCop, Standard, Flog, Reek, or cyclomatic-complexity configuration. Its Rakefile supplies `check_syntax`, warning-enabled spec commands, and optional `visibility_checker` integration. Its contribution guide asks contributors to follow surrounding code style rather than prescribing an automatic formatter.
28+
29+
This repository now provides `check_syntax`, `check_visibility`, `lint`, and `check` tasks. Syntax and visibility failures were tested with deliberately invalid temporary probes and correctly returned nonzero exit statuses. These checks apply only to project code, not ignored upstream checkouts. No wholesale reformatting was performed.
30+
31+
Prism AST source ranges identified `Configuration#initialize` (58 lines) and `Dataset#libsql_types` (50 lines) as the longest methods. Configuration now separates location normalization, URL validation, credentials, replication options, and option validation. `ResultTypes` handles projection origins and `TypeConverter` handles semantic conversions. `Dataset` shrank from 130 to 58 lines. The longest library method is now 24 lines; the largest library file is 178 lines. These are source-size measurements, not cyclomatic scores.
32+
33+
## Verification
34+
35+
- `bundle exec rake check upstream remote_local`: 40 local tests / 196 assertions; 901 upstream tests / 7469 assertions / six upstream skips; five real native HTTP tests / 24 assertions. No failures or errors. Current-bundle syntax, warnings, and adapter visibility checks pass.
36+
- The 40 local tests also pass with Sequel 5.80.0. That older Sequel emits a Ruby 4 URI deprecation warning from its own code; it is not an adapter warning.
37+
- The CI workflow parses and invokes `rake check`, but its Linux/Ruby matrix has not been executed here.
38+
39+
Hosted Turso authentication/TLS, live replica sync/read-your-writes behavior, and encryption still need real service tests. Local descriptor support or mocked native calls would not establish those guarantees, so this review does not claim them.
40+
41+
## Source pointers
42+
43+
- [Sequel Rakefile](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/Rakefile)
44+
- [Sequel SQLite specs](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/spec/adapters/sqlite_spec.rb)
45+
- [Sequel contribution guide](https://github.com/jeremyevans/sequel/blob/75b425dd1c1f34908426dd70371d14e4afb9c933/CONTRIBUTING)
46+
- [libsql-activerecord example tests](https://github.com/tursodatabase/libsql-activerecord/tree/4873624743b046dde6c0188963b22576d8341e3a/examples/railsapp/test)

0 commit comments

Comments
 (0)