finox 0.1.0-aarch64-linux → 0.2.0-aarch64-linux

data/README.md

@@ -2,44 +2,49 @@
 
 A MySQL query parser for Ruby, powered by [sqlparser-rs](https://github.com/apache/datafusion-sqlparser-rs).
 
-Finox parses SQL with Rust and returns the AST as plain Ruby Hashes and Arrays.
+Finox parses SQL with Rust and exposes tables, columns, fingerprints and the raw AST.
 
 ## Installation
 
-Add to your Gemfile:
-
 ```bash
 bundle add finox
 ```
 
-Or install directly:
+Or without Bundler:
 
 ```bash
 gem install finox
 ```
 
-A Rust toolchain is required to build the native extension.
+Precompiled native gems are available for Ruby 3.1–4.0 on the following
+platforms, so installation there requires no Rust toolchain:
+
+| OS      | Platforms                                        |
+| ------- | ------------------------------------------------ |
+| Linux   | x86_64, aarch64 (glibc and musl variants)        |
+| macOS   | x86_64, arm64                                    |
+| Windows | x64-mingw-ucrt                                   |
+
+On any other platform the source gem is installed instead, and compiling it
+requires a Rust toolchain.
 
 ## Usage
 
+`Finox.parse` returns a `Finox::Result`:
+
 ```ruby
 require "finox"
 
-ast = Finox.parse("SELECT `name` FROM `users` WHERE id = 1")
-# => [{"Query" => {with: nil, body: {"Select" => {...}}, ...}}]
+result = Finox.parse("SELECT `name` FROM `users` WHERE id = 1")
+# => #<Finox::Result>
 
-ast.dig(0, "Query", :body, "Select", :projection)
-# => [{"UnnamedExpr" =>
-#       {"Identifier" =>
-#         {value: "name",
-#          quote_style: "`",
-#          span: {start: {line: 1, column: 8}, end: {line: 1, column: 14}}}}}]
+result.tables          # => ["users"]
+result.columns         # => ["name", "id"]
+result.statement_types # => ["Query"]
+result.normalize       # => "SELECT `name` FROM `users` WHERE id = ?"
+result.fingerprint     # => "24e307ca0f02abfc"
 ```
 
-`Finox.parse` returns one Hash per statement, so `"SELECT 1; SELECT 2"` yields an array of two.
-
-Key convention (from serde's externally tagged enums): enum variant names are `String` keys (`"Query"`, `"Select"`, `"Identifier"`), struct fields are `Symbol` keys (`:body`, `:projection`, `:value`).
-
 Invalid SQL raises `Finox::ParseError`:
 
 ```ruby
@@ -47,6 +52,69 @@ Finox.parse("SELEKT 1")
 # => Finox::ParseError: sql parser error: Expected: an SQL statement, found: SELEKT at Line: 1, Column: 1
 ```
 
+### Table classification
+
+`#select_tables`, `#dml_tables` and `#ddl_tables` classify the referenced
+tables by how they are used: read, written by DML (`INSERT` / `UPDATE` /
+`DELETE`) or targeted by DDL (`CREATE TABLE` / `ALTER TABLE` / `DROP TABLE` /
+`TRUNCATE` etc.). A table appearing in multiple roles is listed in each.
+
+```ruby
+result = Finox.parse("INSERT INTO logs SELECT message FROM events; DROP TABLE archives")
+
+result.tables        # => ["logs", "events", "archives"]
+result.select_tables # => ["events"]
+result.dml_tables    # => ["logs"]
+result.ddl_tables    # => ["archives"]
+```
+
+#### Known limitations
+
+Extraction is syntactic, with no schema knowledge and only coarse scope
+resolution:
+
+- A CTE name shadows a same-named real table everywhere in the statement,
+  even inside the CTE's own definition.
+- Multi-table `UPDATE` (`UPDATE t1 JOIN t2 ... SET t2.x = 1`) reports only
+  `t1` in `#dml_tables`.
+- `#columns` does not resolve table aliases (`u.id` stays `u.id`).
+
+### Normalization and fingerprints
+
+`#normalize` replaces literals with `?` placeholders and deparses from the
+AST, so formatting and keyword case are normalized as well. `#fingerprint` is
+a 64-bit hex hash (xxhash64) of the normalized SQL — stable across literal
+and formatting differences, but not guaranteed to be stable across finox
+versions, since the normalized form depends on the bundled sqlparser-rs.
+Recompute stored fingerprints when upgrading finox.
+
+```ruby
+Finox.parse("select * from users where id=1").normalize
+# => "SELECT * FROM users WHERE id = ?"
+
+Finox.parse("select * from users where id=1").fingerprint ==
+  Finox.parse("SELECT * FROM users WHERE id = 42").fingerprint
+# => true
+```
+
+### Raw sqlparser-rs AST
+
+For anything not covered above, `#statements` exposes sqlparser-rs's raw AST of each parsed statement as plain
+Ruby Hashes and Arrays:
+
+```ruby
+ast = Finox.parse("SELECT `name` FROM `users` WHERE id = 1").statements.first
+# => {"Query" => {"with" => nil, "body" => {"Select" => {...}}, ...}}
+
+ast.dig("Query", "body", "Select", "projection")
+# => [{"UnnamedExpr" =>
+#       {"Identifier" =>
+#         {"value" => "name",
+#          "quote_style" => "`",
+#          "span" => {"start" => {"line" => 1, "column" => 8},
+#                     "end" => {"line" => 1, "column" => 14}}}}}]
+```
+
 ## Development
 
 ```bash
@@ -58,3 +126,7 @@ bundle exec rake          # compile + spec + rubocop
 ## License
 
 [MIT](LICENSE.txt)
+
+Precompiled gems statically link Rust crates, including sqlparser-rs
+(Apache-2.0). See [LICENSE-THIRD-PARTY.txt](LICENSE-THIRD-PARTY.txt) for
+their licenses and attributions.

data/lib/finox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Finox
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finox
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: aarch64-linux
 authors:
 - kyuuri1791
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-07-17 00:00:00.000000000 Z
+date: 2026-07-18 00:00:00.000000000 Z
 dependencies: []
 description: Parses MySQL queries with the Rust sqlparser crate (via magnus) and returns
   the AST as plain Ruby Hashes and Arrays.
@@ -17,9 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
+- LICENSE-THIRD-PARTY.txt
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -28,6 +27,7 @@ files:
 - lib/finox/3.2/finox.so
 - lib/finox/3.3/finox.so
 - lib/finox/3.4/finox.so
+- lib/finox/4.0/finox.so
 - lib/finox/version.rb
 homepage: https://github.com/kyuuri1791/finox
 licenses:
@@ -48,7 +48,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.1'
   - - "<"
     - !ruby/object:Gem::Version
-      version: 3.5.dev
+      version: 4.1.dev
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,8 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.1
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes