granita 0.0.3-aarch64-linux → 0.0.4-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73a04013e2c85fbfaba2f867b680f4ba5786315364f016eff3c15ca7bd8c8954
-  data.tar.gz: 2549c3b46a84eff37b18aa03f378970832f3b2378b1cc7d2c6ec2ca492accda4
+  metadata.gz: b33f8759d6ec6a83591a4d88ee834c7be6d862990e081bc9579bb3aa4499868b
+  data.tar.gz: 782a66757a36cd6f8fc619bca524277065bbfea6562dcf78f61b8c44b4b49a90
 SHA512:
-  metadata.gz: d4689fe88702b6f316da59eebc91189b4139e5ca61db25d7c49171f3e5d7150601459854f61fecd1e353af88ba8be4ee55034e3d407deabb1fd1f1f9810f4bd9
-  data.tar.gz: d2b0857372abf5f793255e42d764664f13eddcc8710b3b8677a45ab3a16552cf3354975fe380e80713e99362d07948c0d90e47ccca2defe3fdb4b1022b8016ca
+  metadata.gz: 07c5437c70e3bc9434bafe3e1a1d8b26fb6072149e98b5d9f902f2bc350e7bab9f1939bf1b38669c83a3673ec87dbdbaa7e4e7e8d792fd39374311cb6a169ee5
+  data.tar.gz: da11cbc755206de9c2841871fafd68751f99e88c1957b7ce9ca1740476286031ed2244b29903af31d5272489aafc054c55e64347ef7dac60335e51a6c3337b07

data/README.md

@@ -14,4 +14,37 @@ Granita is in beta and is meant as a drop-in replacement for `srb tc`.
     granita          # typecheck the project described by sorbet/config
     granita --lsp    # run the language server
 
+## Semantic graph API
+
+The native graph API runs Granita's semantic pipeline and exposes an immutable query snapshot:
+
+```ruby
+require "granita"
+
+graph = Granita::Graph.index(Dir["lib/**/*.rb"])
+
+graph.documents.each { |document| puts document.path }
+graph.definitions.each { |definition| puts definition.full_name }
+graph.declarations.each { |declaration| puts declaration.full_name }
+graph.constant_references.each { |reference| puts reference.name }
+graph.calls.each do |call|
+  puts "#{call.receiver_types.join(' | ')}##{call.name} -> #{call.target_ids.join(', ')}"
+end
+
+product = graph["Shop::Product"]
+puts product.definition_ids
+
+result = graph.cypher(<<~CYPHER)
+  MATCH (call:Call)-[:TARGETS]->(method:Method)
+  WHERE call.receiver_type CONTAINS 'Shop::Product'
+  RETURN call.name, method.name
+CYPHER
+result.rows.each { |row| puts row }
+puts result.render(:table)
+```
+
+For editor buffers, generated source, or non-UTF-8 Ruby, use `Granita::Graph.from_sources("path.rb" => source)`; source bytes are preserved. Calls are present for typed and untyped files. Inferred calls expose `receiver_types` and resolved `target_ids`; uninferred or unresolved calls leave both arrays empty.
+
+Locations contain zero-based, end-exclusive byte offsets. `Definition#location` covers the full construct and `#declaration_location` identifies its header/name. Declarations from the bundled RBI payload that are referenced by workspace code have `external == true`. `Granita::Query.parse` allows a parsed read-only Cypher query to be reused across graph snapshots, and `Granita::Query.schema(:json)` describes the available labels, properties, and relationships.
+
 Set `SRB_SORBET_EXE` to run a different typechecker binary.

data/include/granita_graph.h

@@ -0,0 +1,56 @@
+#ifndef GRANITA_GRAPH_H
+#define GRANITA_GRAPH_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Opaque, immutable semantic graph. */
+typedef struct GranitaGraph GranitaGraph;
+/** Opaque, reusable parsed Cypher query. */
+typedef struct GranitaQuery GranitaQuery;
+
+/**
+ * Builds a graph from UTF-8 JSON. Accepted inputs are:
+ *   {"paths":["lib/a.rb", "lib/b.rb"]}
+ *   {"sources":[{"path":"a.rb", "source":[99,108,97,115,115,32,65,59,32,101,110,100]}]}
+ *
+ * Returns NULL on failure and stores an allocated error in *error_out when error_out is non-NULL.
+ */
+GranitaGraph *granita_graph_new_json(const char *input, char **error_out);
+void granita_graph_free(GranitaGraph *graph);
+
+/**
+ * Returns an allocated UTF-8 JSON string for one collection. `collection` is one of
+ * "documents", "definitions", "declarations", "constant_references", "calls", or "all".
+ * Returns NULL on failure and stores an allocated error in *error_out when non-NULL.
+ */
+char *granita_graph_query_json(const GranitaGraph *graph, const char *collection, char **error_out);
+/** Parses a read-only Cypher query. */
+GranitaQuery *granita_query_parse(const char *query, char **error_out);
+void granita_query_free(GranitaQuery *query);
+
+/**
+ * Executes a parsed Cypher query and returns a JSON array of row objects. Returned node values
+ * include stable `id`, `label`, and `name` fields.
+ */
+char *granita_query_execute_json(
+    const GranitaGraph *graph,
+    const GranitaQuery *query,
+    char **error_out
+);
+
+/** Returns the queryable schema. `format` is "json" or "table". */
+char *granita_query_schema(const char *format, char **error_out);
+
+
+/** Frees strings returned by this API, including errors. */
+void granita_string_free(char *string);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

data/lib/granita/graph.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "fiddle/import"
+require "json"
+require "rbconfig"
+
+module Granita
+  class Graph
+    Document = Struct.new(:id, :path, :definition_ids, :constant_reference_ids, :call_ids, keyword_init: true)
+    Definition = Struct.new(:id, :declaration_id, :kind, :name, :full_name, :location, :declaration_location, :line, keyword_init: true)
+    Declaration = Struct.new(:id, :kind, :name, :full_name, :owner_id, :definition_ids, :constant_reference_ids, :visibility, :external, keyword_init: true)
+    ConstantReference = Struct.new(:id, :name, :target_id, :location, keyword_init: true)
+    Call = Struct.new(:id, :name, :receiver_types, :target_ids, :location, keyword_init: true)
+    Location = Struct.new(:document_id, :start, :end, keyword_init: true)
+
+    module Native
+      extend Fiddle::Importer
+
+      extension = RbConfig::CONFIG.fetch("DLEXT")
+      default = File.expand_path("../../libexec/granita_graph.#{extension}", __dir__)
+      dlload ENV.fetch("GRANITA_GRAPH_LIBRARY", default)
+
+      extern "void *granita_graph_new_json(const char *, void *)"
+      extern "void granita_graph_free(void *)"
+      extern "char *granita_graph_query_json(void *, const char *, void *)"
+      extern "void *granita_query_parse(const char *, void *)"
+      extern "void granita_query_free(void *)"
+      extern "char *granita_query_execute_json(void *, void *, void *)"
+      extern "char *granita_query_schema(const char *, void *)"
+      extern "void granita_string_free(void *)"
+    end
+
+    class << self
+      def index(paths)
+        new(paths: Array(paths).map { |path| File.expand_path(path) })
+      end
+
+      def from_sources(sources)
+        entries = sources.map { |path, source| {path: path.to_s, source: source.to_s.b.bytes} }
+        new(sources: entries)
+      end
+
+      private :new
+    end
+
+    def initialize(input)
+      error = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      error[0, Fiddle::SIZEOF_VOIDP] = [0].pack(pointer_pack)
+      address = Native.granita_graph_new_json(JSON.generate(input), error)
+      raise_native_error(error) if address.to_i.zero?
+
+      @pointer = Fiddle::Pointer.new(address.to_i, 0, Native["granita_graph_free"])
+    end
+
+    def documents
+      query("documents").map { |row| Document.new(**symbolize(row)) }
+    end
+
+    def definitions
+      query("definitions").map do |row|
+        values = record(row)
+        values[:declaration_location] = Location.new(**symbolize(values.fetch(:declaration_location)))
+        Definition.new(**values)
+      end
+    end
+
+    def declarations
+      query("declarations").map { |row| Declaration.new(**symbolize(row)) }
+    end
+
+    def constant_references
+      query("constant_references").map { |row| ConstantReference.new(**record(row)) }
+    end
+
+    def calls
+      query("calls").map { |row| Call.new(**record(row)) }
+    end
+
+    def declaration(name)
+      declarations.find { |declaration| declaration.full_name == name || declaration.full_name == name.delete_prefix("::") }
+    end
+    alias_method :[], :declaration
+    def cypher(query)
+      Granita::Query.parse(query).run(self)
+    end
+
+
+    private
+
+    def native_handle
+      @pointer
+    end
+
+    def resolve_query_node(encoded)
+      kind, id = encoded.split(":", 2)
+      id = Integer(id, exception: false)
+      return unless id
+
+      @query_node_indexes ||= {}
+      records = case kind
+      when "doc"
+        @query_node_indexes[:documents] ||= documents.to_h { |record| [record.id, record] }
+      when "def"
+        @query_node_indexes[:definitions] ||= definitions.to_h { |record| [record.id, record] }
+      when "decl"
+        @query_node_indexes[:declarations] ||= declarations.to_h { |record| [record.id, record] }
+      when "call"
+        @query_node_indexes[:calls] ||= calls.to_h { |record| [record.id, record] }
+      else
+        return
+      end
+      records[id]
+    end
+
+    def query(collection)
+      error = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      error[0, Fiddle::SIZEOF_VOIDP] = [0].pack(pointer_pack)
+      result = Native.granita_graph_query_json(@pointer, collection, error)
+      raise_native_error(error) if result.to_i.zero?
+
+      pointer = Fiddle::Pointer.new(result.to_i)
+      json = pointer.to_s
+      Native.granita_string_free(pointer)
+      JSON.parse(json)
+    end
+
+    def record(row)
+      values = symbolize(row)
+      values[:location] = Location.new(**symbolize(values.fetch(:location)))
+      values
+    end
+
+    def symbolize(hash)
+      hash.transform_keys!(&:to_sym)
+    end
+
+    def raise_native_error(error)
+      address = error[0, Fiddle::SIZEOF_VOIDP].unpack1(pointer_pack)
+      message = "Granita graph operation failed"
+      unless address.zero?
+        pointer = Fiddle::Pointer.new(address)
+        message = pointer.to_s
+        Native.granita_string_free(pointer)
+      end
+      raise ArgumentError, message
+    end
+
+    def pointer_pack
+      "J"
+    end
+  end
+end

data/lib/granita/query.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "graph"
+
+module Granita
+  class Query
+    class SyntaxError < ArgumentError; end
+    class ExecutionError < StandardError; end
+
+    class Result
+      attr_reader :rows
+
+      def initialize(rows, raw_rows)
+        @rows = rows.freeze
+        @raw_rows = raw_rows.freeze
+      end
+
+      def render(format = :table)
+        case format.to_sym
+        when :json
+          JSON.generate(@raw_rows)
+        when :table
+          render_table
+        else
+          raise ArgumentError, "unknown query output format `#{format}`"
+        end
+      end
+
+      private
+
+      def render_table
+        return "" if @raw_rows.empty?
+
+        columns = @raw_rows.flat_map(&:keys).uniq
+        values = @raw_rows.map do |row|
+          columns.map { |column| display(row[column]) }
+        end
+        widths = columns.each_index.map do |index|
+          ([columns[index].length] + values.map { |row| row[index].length }).max
+        end
+        lines = []
+        lines << columns.each_index.map { |index| columns[index].ljust(widths[index]) }.join(" | ")
+        lines << widths.map { |width| "-" * width }.join("-+-")
+        values.each do |row|
+          lines << row.each_index.map { |index| row[index].ljust(widths[index]) }.join(" | ")
+        end
+        lines << ""
+        lines << "#{values.length} #{values.length == 1 ? "row" : "rows"}"
+        "#{lines.join("\n")}\n"
+      end
+
+      def display(value)
+        case value
+        when Hash
+          value["name"] || JSON.generate(value)
+        when Array
+          "[#{value.map { |item| display(item) }.join(", ")}]"
+        when nil
+          ""
+        else
+          value.to_s
+        end
+      end
+    end
+
+    class << self
+      def parse(source)
+        address = call_native(SyntaxError) do |error|
+          Graph::Native.granita_query_parse(source.to_s, error)
+        end
+        new(address)
+      end
+
+      def schema(format = :table)
+        address = call_native(ArgumentError) do |error|
+          Graph::Native.granita_query_schema(format.to_s, error)
+        end
+        take_string(address)
+      end
+
+      private
+
+      def call_native(error_class)
+        error = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+        error[0, Fiddle::SIZEOF_VOIDP] = [0].pack("J")
+        address = yield(error)
+        return address unless address.to_i.zero?
+
+        pointer_address = error[0, Fiddle::SIZEOF_VOIDP].unpack1("J")
+        message = "Granita query operation failed"
+        unless pointer_address.zero?
+          pointer = Fiddle::Pointer.new(pointer_address)
+          message = pointer.to_s
+          Graph::Native.granita_string_free(pointer)
+        end
+        raise error_class, message
+      end
+
+      def take_string(address)
+        pointer = Fiddle::Pointer.new(address.to_i)
+        value = pointer.to_s
+        Graph::Native.granita_string_free(pointer)
+        value
+      end
+
+      private :new
+    end
+
+    def initialize(address)
+      @pointer = Fiddle::Pointer.new(address.to_i, 0, Graph::Native["granita_query_free"])
+    end
+
+    def run(graph)
+      address = self.class.__send__(:call_native, ExecutionError) do |error|
+        Graph::Native.granita_query_execute_json(
+          graph.__send__(:native_handle),
+          @pointer,
+          error,
+        )
+      end
+      raw_rows = JSON.parse(self.class.__send__(:take_string, address))
+      rows = raw_rows.map do |row|
+        row.transform_values { |value| convert_value(graph, value) }
+      end
+      Result.new(rows, raw_rows)
+    end
+
+    private
+
+    def convert_value(graph, value)
+      case value
+      when Array
+        value.map { |item| convert_value(graph, item) }
+      when Hash
+        if value["id"].is_a?(String) && value["id"].match?(/\A(?:doc|def|decl|call):\d+\z/)
+          graph.__send__(:resolve_query_node, value["id"]) || value
+        else
+          value.transform_values { |item| convert_value(graph, item) }
+        end
+      else
+        value
+      end
+    end
+  end
+end

data/lib/granita/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Granita
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/lib/granita.rb

@@ -3,6 +3,8 @@
 require_relative "granita/version"
 
 module Granita
+  autoload :Graph, File.expand_path("granita/graph", __dir__)
+  autoload :Query, File.expand_path("granita/query", __dir__)
   # Absolute path to the bundled typechecker binary.
   def self.binary_path
     File.expand_path("../libexec/sorbet", __dir__)

data/libexec/granita_graph.so

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: data/libexec/granita_graph.so
+size: 46990064 bytes
+sha256: 4e77b34ec247642c8d05af2130fe5402d1c0a86c96429e1eb50b48146f722b13

data/libexec/sorbet

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/libexec/sorbet
-size: 60919864 bytes
-sha256: 5bf02070ca52a26ddc2579e454143d040df9a7db2d633105ef8d49a2ac63bc06
+size: 60922008 bytes
+sha256: ac6d6a3025048011b933edfeead667a7b2a7656d25edfedd95f9bee015c1dc6c

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: granita
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: aarch64-linux
 authors:
 - Alexandre Terrasa
@@ -18,8 +18,12 @@ files:
 - NOTICE
 - README.md
 - exe/granita
+- include/granita_graph.h
 - lib/granita.rb
+- lib/granita/graph.rb
+- lib/granita/query.rb
 - lib/granita/version.rb
+- libexec/granita_graph.so
 - libexec/sorbet
 homepage: https://github.com/Morriar/granita
 licenses: