vetra 0.1.0.pre.alpha.4

data/lib/vetra/cli.rb

@@ -0,0 +1,64 @@
+require "optparse"
+require_relative "../vetra"
+
+module Vetra
+  class CLI
+    def self.run(arguments, out: $stdout, err: $stderr)
+      options = { root: Dir.pwd, sources: false, format: nil, fail_on_breaking: false }
+      parser = OptionParser.new do |flags|
+        flags.banner = "Uso: vetra graph:build|graph:check|graph:link [--root diretório]\n     vetra graph:validate [arquivo] [--root diretório] [--sources]\n     vetra graph:diff ANTERIOR POSTERIOR [--root diretório] [--format text|json] [--fail-on-breaking]"
+        flags.on('--root PATH', 'Raiz da aplicação') { |value| options[:root] = value }
+        flags.on('--sources', 'Também verificar manifesto em graph:validate') { options[:sources] = true }
+        flags.on('--format FORMAT', %w[text json], 'Formato de graph:diff: text ou json') { |value| options[:format] = value }
+        flags.on('--fail-on-breaking', 'Sair com código 3 se o diff apontar quebra potencial') { options[:fail_on_breaking] = true }
+        flags.on('-h', '--help', 'Mostrar ajuda') { out.puts(flags); return 0 }
+        flags.on('--version', 'Mostrar versão do protótipo') { out.puts(VERSION); return 0 }
+      end
+      args = parser.parse(arguments.dup)
+      command = args.shift
+      unless %w[graph:build graph:check graph:validate graph:diff graph:link].include?(command)
+        err.puts(parser)
+        return 2
+      end
+      if command == 'graph:diff'
+        raise OptionParser::InvalidArgument, 'graph:diff exige duas entradas e não aceita --sources' unless args.size == 2 && !options[:sources]
+        source = Graph::DiffSource.new(root: options[:root])
+        report = Graph::Diff.new.compare(*args.map { |input| source.read(input) })
+        report.data['warnings'].each do |warning|
+          label = warning['side'] == 'before' ? 'anterior' : 'posterior'
+          diagnostic = Graph::Diagnostic.new(code: warning['code'], message: warning['message'], pointer: warning['pointer'], source: warning['source'], severity: :warning)
+          err.puts("[#{label}] #{diagnostic}")
+        end
+        out.write(options[:format] == 'json' ? report.to_json : report.to_text)
+        return options[:fail_on_breaking] && report.breaking? ? 3 : 0
+      end
+      if options[:format] || options[:fail_on_breaking] || (command != 'graph:validate' && (!args.empty? || options[:sources])) || args.size > 1
+        raise OptionParser::InvalidArgument, 'argumentos incompatíveis com o comando'
+      end
+      compiler = Graph::Compiler.new(root: options[:root])
+      result = case command
+      when 'graph:build' then compiler.write
+      when 'graph:check' then compiler.check
+      when 'graph:validate'
+        compiler.validate_file(args.first || compiler.artifact, sources: options[:sources])
+      when 'graph:link' then compiler.link
+      end
+      result.warnings.each { |diagnostic| err.puts(diagnostic) }
+      if command == 'graph:link'
+        out.puts("#{command}: OK — #{result.implementation_ids.size} blocos Ruby vinculados; #{result.builtin_bindings.size} descritores de primitivas sem executor; #{result.document.fetch('digest')}")
+      else
+        out.puts("#{command}: OK — #{result.document.fetch('nodes').size} nós, #{result.document.fetch('digest')}")
+      end
+      0
+    rescue Graph::Error => e
+      e.diagnostics.each { |diagnostic| err.puts(diagnostic) }
+      1
+    rescue OptionParser::ParseError => e
+      err.puts(e.message)
+      2
+    rescue SystemCallError => e
+      err.puts("[filesystem] #{e.class}: não foi possível ler ou gravar o projeto.")
+      1
+    end
+  end
+end

data/lib/vetra/graph/analysis.rb

@@ -0,0 +1,94 @@
+require "prism"
+
+module Vetra
+  module Graph
+    class Analysis
+      DYNAMIC = %i[send public_send __send__ const_get eval instance_eval class_eval module_eval define_method instance_variable_get].freeze
+      PROCESS_CALLS = %i[system exec spawn fork open sleep gets puts print warn rand srand require require_relative load exit abort at_exit trap autoload].freeze
+      WRITE_CALLS = %i[create! update! delete! insert update delete save! destroy! add_member! remove_member!].freeze
+      EFFECT_CLASSES = /\A(?:File|IO|Socket|TCPSocket|UDPSocket|Process|Thread|Random|SecureRandom|Net::HTTP|OpenURI|ENV|Sequel|ActiveRecord|PG)(?:::|\z)/
+
+      def initialize(manifest)
+        @manifest = manifest
+        @trees = {}
+      end
+
+      def inspect_block(block, declared_uses, declaration_source:, declaration_kind:)
+        path, line = block.source_location
+        source = @manifest.source(path, line)
+        parsed = @trees[source['path']] ||= Prism.parse(@manifest.read(source['path']))
+        declarations = descendants(parsed.value).select do |node|
+          node.is_a?(Prism::CallNode) && node.name.to_s == declaration_kind && node.block.is_a?(Prism::BlockNode) && node.block.location.start_line == declaration_source['line']
+        end
+        unless source['path'] == declaration_source['path'] && declarations.size == 1
+          raise Error.single('analysis_binding', 'O bloco deve pertencer à declaração exata da operação.', source: declaration_source)
+        end
+        candidates = descendants(declarations.first.block.body).select do |node|
+          node.is_a?(Prism::CallNode) && node.name == :call && node.block.is_a?(Prism::BlockNode) && node.block.location.start_line == line
+        end
+        unless candidates.size == 1
+          raise Error.single("analysis_binding", "O call deve estar dentro da declaração da operação, em uma linha própria e sem ambiguidade.", source: declaration_source)
+        end
+        parameters = block.parameters
+        expected = declared_uses.map { |name| name.split('.').last }
+        unless parameters.size == expected.size + 1 && parameters.all? { |kind, name| %i[opt req].include?(kind) && name } && parameters.drop(1).map { |_, name| name.to_s } == expected
+          raise Error.single("implementation_parameters", "call exige um parâmetro de entrada seguido das capacidades na ordem de uses: #{expected.join(', ')}.", source: source)
+        end
+        constants, dynamic, forbidden, writes = [], [], [], []
+        descendants(candidates.first.block.body).each do |node|
+          if node.is_a?(Prism::ConstantReadNode) || node.is_a?(Prism::ConstantPathNode)
+            constants << node.location.slice.delete_prefix('::')
+          elsif node.is_a?(Prism::XStringNode) || node.is_a?(Prism::InterpolatedXStringNode)
+            forbidden << 'Kernel#`'
+          elsif node.is_a?(Prism::CallNode)
+            receiver = node.receiver
+            constant = if receiver.is_a?(Prism::ConstantReadNode) || receiver.is_a?(Prism::ConstantPathNode)
+              receiver.location.slice.delete_prefix('::')
+            end
+            name = node.name
+            if constant&.match?(EFFECT_CLASSES) || (%w[Time DateTime].include?(constant) && %i[now new].include?(name)) || (constant == 'Date' && name == :today) || (constant == 'Kernel' && PROCESS_CALLS.include?(name)) || (!receiver && PROCESS_CALLS.include?(name))
+              effect = "#{constant || 'Kernel'}.#{name}"
+              forbidden << effect
+              constants << effect
+            end
+            dynamic << name.to_s if DYNAMIC.include?(name)
+            if !receiver && ![:fail!].include?(name) && !PROCESS_CALLS.include?(name)
+              dynamic << "unresolved_call:#{name}"
+            end
+            if receiver.is_a?(Prism::LocalVariableReadNode) && WRITE_CALLS.include?(name)
+              attributes = node.arguments&.arguments&.select { |arg| arg.is_a?(Prism::KeywordHashNode) || arg.is_a?(Prism::HashNode) } || []
+              values = attributes.flat_map(&:elements).filter_map do |pair|
+                next unless pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode)
+                known, value = literal(pair.value)
+                { 'name' => pair.key.unescaped, 'known' => known, 'value' => value }
+              end
+              writes << { 'receiver' => receiver.name.to_s, 'fields' => values, 'line' => node.location.start_line }
+            end
+          end
+        end
+        {
+          'source' => source, 'forbidden' => forbidden.uniq.sort, 'writes' => writes,
+          'analysis' => { 'status' => dynamic.empty? ? 'complete' : 'incomplete', 'constants' => constants.uniq.sort, 'dynamic' => dynamic.uniq.sort }
+        }
+      end
+
+      private
+
+      def descendants(node)
+        return [] unless node
+        [node, *node.compact_child_nodes.flat_map { |child| descendants(child) }]
+      end
+
+      def literal(node)
+        case node
+        when Prism::StringNode, Prism::SymbolNode then [true, node.unescaped]
+        when Prism::IntegerNode then [true, node.value]
+        when Prism::TrueNode then [true, true]
+        when Prism::FalseNode then [true, false]
+        when Prism::NilNode then [true, nil]
+        else [false, nil]
+        end
+      end
+    end
+  end
+end

data/lib/vetra/graph/canonical.rb

@@ -0,0 +1,52 @@
+require "json"
+require "digest"
+
+module Vetra
+  module Graph
+    # RFC 8785 for the IR subset: floats are forbidden, so ECMAScript number
+    # rounding is unnecessary. Object keys sort by UTF-16 code units, not UTF-8.
+    module Canonical
+      MAX_INTEGER = (2**53) - 1
+
+      module_function
+
+      def parse(bytes)
+        JSON.parse(bytes, allow_duplicate_key: false, create_additions: false, allow_nan: false)
+      rescue JSON::ParserError, EncodingError, ArgumentError => e
+        raise Error.single("invalid_json", "JSON inválido (#{e.class}).")
+      end
+
+      def dump(value)
+        case value
+        when Hash
+          unless value.keys.all? { |key| key.is_a?(String) }
+            raise Error.single("invalid_data", "Chaves da IR devem ser strings.")
+          end
+          keys = value.keys.sort_by { |key| key.encode(Encoding::UTF_16BE).bytes }
+          "{#{keys.map { |key| "#{dump(key)}:#{dump(value.fetch(key))}" }.join(',')}}"
+        when Array
+          "[#{value.map { |child| dump(child) }.join(',')}]"
+        when String
+          text = value.encode(Encoding::UTF_8)
+          raise Error.single("invalid_data", "String UTF-8 inválida.") unless text.valid_encoding?
+          JSON.generate(text)
+        when Integer
+          raise Error.single("invalid_data", "Inteiro fora do intervalo seguro da IR.") if value.abs > MAX_INTEGER
+          value.to_s
+        when TrueClass then "true"
+        when FalseClass then "false"
+        when NilClass then "null"
+        else
+          raise Error.single("invalid_data", "Tipo #{value.class} não permitido na IR; decimais usam strings.")
+        end
+      rescue EncodingError => e
+        raise Error.single("invalid_data", "Codificação inválida (#{e.class}).")
+      end
+
+      def digest(document)
+        payload = document.reject { |key, _| key == "digest" }
+        "sha256:#{Digest::SHA256.hexdigest(dump(payload))}"
+      end
+    end
+  end
+end

data/lib/vetra/graph/capabilities.rb

@@ -0,0 +1,22 @@
+module Vetra
+  module Graph
+    module Capabilities
+      module_function
+
+      def reference(name, domain:, operation_kind:, nodes:, source: nil)
+        id = name.include?('.') ? name : "#{domain}.#{name}"
+        capability = nodes[['capability', id]]
+        unless capability
+          raise Error.single('reference_missing', "Declare effect ou repositório #{id} antes de usá-lo.", source: source)
+        end
+        if %w[query handler].include?(operation_kind) && capability.dig('config', 'type') == 'repository' && capability.dig('config', 'access') == 'read_write'
+          id = "#{id}_read"
+        end
+        unless nodes.key?(['capability', id])
+          raise Error.single('reference_missing', "Capacidade resolvida não declarada: #{id}.", source: source)
+        end
+        Data.reference('capability', id)
+      end
+    end
+  end
+end

data/lib/vetra/graph/compiler.rb

@@ -0,0 +1,119 @@
+require "tempfile"
+
+module Vetra
+  module Graph
+    Result = Struct.new(:document, :warnings, :implementation_ids, keyword_init: true) do
+      def bytes
+        "#{Canonical.dump(document)}\n"
+      end
+    end
+
+    class Compiler
+      attr_reader :root
+
+      def initialize(root: Dir.pwd)
+        @root = Pathname.new(root).realpath
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        raise Error.single('project_root', 'Diretório do projeto não existe.')
+      end
+
+      def build
+        manifest = Manifest.new(root)
+        document, registry, warnings = compile(manifest)
+        Manifest.new(root).verify!(document)
+        Data.freeze(Result.new(document: document, warnings: warnings, implementation_ids: registry.bindings.keys.sort))
+      end
+
+      def write
+        result = build
+        directory = root.join('.vetra')
+        directory.mkdir unless directory.exist?
+        unless directory.realpath.to_s.start_with?("#{root}/") && !directory.symlink?
+          raise Error.single('artifact_path', '.vetra deve ser um diretório dentro do projeto.')
+        end
+        Tempfile.create(['graph-', '.json'], directory.to_s) do |file|
+          file.binmode
+          file.write(result.bytes)
+          file.flush
+          file.fsync
+          file.chmod(0o666 & ~File.umask)
+          file.close
+          File.rename(file.path, artifact.to_s)
+        end
+        result
+      end
+
+      def check
+        result = build
+        unless artifact.file? && !artifact.symlink? && artifact.binread == result.bytes
+          raise Error.single('graph_stale', 'IR ausente ou desatualizada; execute graph:build e revise .vetra/graph.json.')
+        end
+        result
+      end
+
+      def validate_file(path, sources: false)
+        document = Canonical.parse(File.binread(path))
+        validator = Validator.new
+        validator.validate!(document)
+        Manifest.new(root).verify!(document) if sources
+        Data.freeze(Result.new(document: document, warnings: validator.warnings, implementation_ids: []))
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        raise Error.single('graph_missing', 'Arquivo da IR não existe.')
+      end
+
+      def artifact
+        root.join('.vetra/graph.json')
+      end
+
+      def link
+        bytes = artifact_bytes
+        document = Canonical.parse(bytes)
+        Validator.new.validate!(document)
+        unless bytes == "#{Canonical.dump(document)}\n"
+          raise Error.single('graph_not_canonical', 'O artefato deve usar JSON canônico seguido de LF; execute graph:build no pipeline.')
+        end
+        producer = document.fetch('producer')
+        unless producer['version'] == Vetra::VERSION && producer['ruby_version'] == RUBY_VERSION
+          raise Error.single('producer_mismatch', 'Versões do Vetra/Ruby diferem do build; carregue o pacote com as versões registradas.', pointer: '/producer')
+        end
+        manifest = Manifest.new(root)
+        manifest.verify!(document)
+        Data.freeze(document)
+
+        # Registration is needed to recreate Ruby closures in this process. The
+        # normalized declaration is an audit only: it never replaces the artifact.
+        audit, registry, warnings = compile(manifest, ir_version: document.fetch('ir_version'))
+        unless Canonical.dump(audit) == Canonical.dump(document)
+          raise Error.single('graph_model_mismatch', 'As declarações carregadas diferem da IR aprovada; reconstrua e revise o pacote.')
+        end
+        linked = Linker.new(document, manifest).link(registry, warnings: warnings)
+        Manifest.new(root).verify!(document)
+        unless artifact_bytes == bytes
+          raise Error.single('graph_changed', 'O artefato mudou durante a vinculação; use um pacote imutável.')
+        end
+        linked
+      end
+
+      private
+
+      def compile(manifest, ir_version: Schema::VERSION)
+        registry = DeclarationLoader.new(manifest).load
+        document = Normalizer.new(registry, manifest, ir_version: ir_version).document
+        warnings = Validator.new.validate!(document)
+        [document, registry, warnings]
+      end
+
+      def artifact_bytes
+        unless artifact.file? && !artifact.symlink?
+          raise Error.single('graph_missing', 'IR ausente ou não regular; publique .vetra/graph.json junto ao pacote.')
+        end
+        if artifact.dirname.symlink? || !artifact.dirname.realpath.to_s.start_with?("#{root}/")
+          raise Error.single('artifact_path', '.vetra deve ser um diretório dentro do projeto.')
+        end
+        artifact.binread
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        raise Error.single('graph_missing', 'Arquivo da IR não existe.')
+      end
+    end
+  end
+end

data/lib/vetra/graph/currency.rb

@@ -0,0 +1,28 @@
+module Vetra
+  module Graph
+    module Currency
+      # ISO 4217 List One (SIX), published 2026-09-17; checked 2026-10-31.
+      # https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml
+      # Source SHA-256: 33139b438657d1cee116ba737807ea71d19d6de4b90f799a09c56f0cc6a1b0ff
+      # Only codes with a numeric CcyMnrUnts are included. N.A. is not zero.
+      EXPONENTS = Data.freeze({
+        0 => %w[BIF CLP DJF GNF ISK JPY KMF KRW PYG RWF UGX UYI VND VUV XAF XOF XPF],
+        2 => %w[
+          AED AFN ALL AMD AOA ARS AUD AWG AZN BAM BBD BDT BMD BND BOB BOV BRL BSD BTN BWP BYN BZD
+          CAD CDF CHE CHF CHW CNY COP COU CRC CUP CVE CZK DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP
+          GEL GHS GIP GMD GTQ GYD HKD HNL HTG HUF IDR ILS INR IRR JMD KES KGS KHR KPW KYD KZT
+          LAK LBP LKR LRD LSL MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MXV MYR MZN NAD
+          NGN NIO NOK NPR NZD PAB PEN PGK PHP PKR PLN QAR RON RSD RUB SAR SBD SCR SDG SEK SGD SHP
+          SLE SOS SRD SSP STN SVC SYP SZL THB TJS TMT TOP TRY TTD TWD TZS UAH USD USN UYU UZS
+          VED VES WST XAD XCD XCG YER ZAR ZMW ZWG
+        ],
+        3 => %w[BHD IQD JOD KWD LYD OMR TND],
+        4 => %w[CLF UYW]
+      }.flat_map { |exponent, codes| codes.map { |code| [code, exponent] } }.to_h)
+
+      def self.exponent(code)
+        EXPONENTS[code]
+      end
+    end
+  end
+end

data/lib/vetra/graph/data.rb

@@ -0,0 +1,48 @@
+module Vetra
+  module Graph
+    module Data
+      module_function
+
+      def freeze(value)
+        case value
+        when Hash
+          value.each { |key, child| freeze(key); freeze(child) }
+        when Array
+          value.each { |child| freeze(child) }
+        when Struct
+          value.each { |child| freeze(child) }
+        end
+        value.freeze
+      end
+
+      def copy(value)
+        case value
+        when Hash then value.to_h { |key, child| [key.dup, copy(child)] }
+        when Array then value.map { |child| copy(child) }
+        when String then value.dup
+        else value
+        end
+      end
+
+      def reference(kind, id)
+        { "kind" => kind, "id" => id }
+      end
+
+      def references(value, pointer = "", &block)
+        case value
+        when Hash
+          if value.keys.sort == %w[id kind]
+            yield value, pointer
+          elsif value["kind"] != "literal"
+            value.each do |key, child|
+              next if key == "annotations"
+              references(child, "#{pointer}/#{key.gsub('~', '~0').gsub('/', '~1')}", &block)
+            end
+          end
+        when Array
+          value.each_with_index { |child, i| references(child, "#{pointer}/#{i}", &block) }
+        end
+      end
+    end
+  end
+end

data/lib/vetra/graph/declaration_loader.rb

@@ -0,0 +1,62 @@
+module Vetra
+  module Graph
+    # Evaluates trusted project declarations once into a fresh, sealed registry.
+    # Both compilation and linking use this path; neither executes a call body.
+    class DeclarationLoader
+      KEYWORD_ERROR = /\A(unknown|missing) keywords?: (.+)\z/
+
+      def initialize(manifest)
+        @manifest = manifest
+      end
+
+      def load
+        registry = Registry.new
+        paths = @manifest.entries.map { |entry| entry['path'] }
+        declarations = paths.grep(/\Aapp\/domains\/.*\.rb\z/).sort_by do |path|
+          [path.split('/')[2], File.basename(path) == 'domain.rb' ? 0 : 1, path]
+        end
+        ['config/app.rb', *declarations].each do |path|
+          domain = path == 'config/app.rb' ? nil : path.split('/')[2]
+          origin = { 'path' => path, 'line' => 1 }
+          if domain && !domain.match?(/\A[a-z][a-z0-9_]*\z/)
+            raise Error.single('domain_name', 'Use nomes de domínio em snake_case ASCII.', source: origin)
+          end
+          context = DSL::Context.new(registry, @manifest, domain, origin)
+          previous = Thread.current[:vetra_graph_context]
+          begin
+            Thread.current[:vetra_graph_context] = context
+            context.evaluate_source(@manifest.read(path), @manifest.root.join(path).to_s)
+          rescue SyntaxError, ArgumentError, TypeError, NameError => error
+            raise(keyword_error(error, path, origin) ||
+              Error.single('dsl_error', "Declaração inválida (#{error.class}): #{error.message.lines.first&.strip}", source: origin))
+          ensure
+            Thread.current[:vetra_graph_context] = previous
+          end
+        end
+        registry.seal!
+      end
+
+      private
+
+      # Uma palavra-chave desconhecida ou ausente numa declaração vira um diagnóstico que nomeia a opção, o método e a
+      # linha da declaração, em vez do ArgumentError do Ruby apontando a linha 1. Qualquer outro erro continua sendo
+      # dsl_error.
+      def keyword_error(error, path, origin)
+        return unless error.is_a?(ArgumentError)
+        match = KEYWORD_ERROR.match(error.message.lines.first.to_s.strip) or return
+        names = match[2].split(', ').map { |name| name.delete_prefix(':') }.join(', ')
+        locations = error.backtrace_locations || []
+        method = locations.first&.base_label
+        place = method&.match?(/\A[a-z_]+[!?]?\z/) ? " em #{method}" : ''
+        file = @manifest.root.join(path).to_s
+        frame = locations.find { |location| (location.absolute_path || location.path) == file }
+        source = frame ? origin.merge('line' => frame.lineno) : origin
+        if match[1] == 'unknown'
+          Error.single('unsupported_option', "Opções não implementadas#{place}: #{names}.", source: source)
+        else
+          Error.single('missing_option', "Opções obrigatórias ausentes#{place}: #{names}.", source: source)
+        end
+      end
+    end
+  end
+end

data/lib/vetra/graph/diagnostic.rb

@@ -0,0 +1,23 @@
+module Vetra
+  module Graph
+    Diagnostic = Struct.new(:code, :message, :pointer, :source, :severity, keyword_init: true) do
+      def to_s
+        origin = source ? "#{source.fetch('path')}:#{source.fetch('line')} " : ""
+        "#{origin}[#{code}] #{pointer || '/'}: #{message}"
+      end
+    end
+
+    class Error < StandardError
+      attr_reader :diagnostics
+
+      def initialize(diagnostics)
+        @diagnostics = diagnostics
+        super(diagnostics.map(&:to_s).join("\n"))
+      end
+
+      def self.single(code, message, source: nil, pointer: "/")
+        new([Diagnostic.new(code: code, message: message, source: source, pointer: pointer, severity: :error)])
+      end
+    end
+  end
+end