polyrun 3.0.1 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +12 -0
  3. data/README.md +4 -2
  4. data/docs/QUALITY.md +80 -0
  5. data/docs/QUALITY_CONFIGURATION.md +95 -0
  6. data/lib/polyrun/cli/ci_shard_run_command.rb +1 -1
  7. data/lib/polyrun/cli/graph_command.rb +68 -0
  8. data/lib/polyrun/cli/help.rb +5 -1
  9. data/lib/polyrun/cli/helpers.rb +3 -2
  10. data/lib/polyrun/cli/mutation_command.rb +67 -0
  11. data/lib/polyrun/cli/quality_commands.rb +65 -0
  12. data/lib/polyrun/cli/run_shards_plan_options.rb +1 -1
  13. data/lib/polyrun/cli/tool_options.rb +48 -0
  14. data/lib/polyrun/cli.rb +17 -1
  15. data/lib/polyrun/config/effective.rb +9 -0
  16. data/lib/polyrun/config/resolver.rb +9 -0
  17. data/lib/polyrun/config/schema.rb +8 -3
  18. data/lib/polyrun/config/suite.rb +6 -1
  19. data/lib/polyrun/config/tool_defaults.rb +42 -0
  20. data/lib/polyrun/config/tool_validation.rb +79 -0
  21. data/lib/polyrun/config/tools.rb +120 -0
  22. data/lib/polyrun/config.rb +6 -4
  23. data/lib/polyrun/graph/client.rb +64 -0
  24. data/lib/polyrun/graph/error.rb +13 -0
  25. data/lib/polyrun/graph/index.rb +75 -0
  26. data/lib/polyrun/graph/inspect.rb +58 -0
  27. data/lib/polyrun/graph/plan.rb +134 -0
  28. data/lib/polyrun/graph/planner.rb +117 -0
  29. data/lib/polyrun/graph/syntax.rb +114 -0
  30. data/lib/polyrun/graph/transaction.rb +81 -0
  31. data/lib/polyrun/graph/worker.rb +55 -0
  32. data/lib/polyrun/graph/workspace.rb +117 -0
  33. data/lib/polyrun/minitest_support.rb +1 -1
  34. data/lib/polyrun/mutation/candidates.rb +91 -0
  35. data/lib/polyrun/mutation/operators.rb +51 -0
  36. data/lib/polyrun/mutation/runner.rb +131 -0
  37. data/lib/polyrun/mutation/subjects.rb +88 -0
  38. data/lib/polyrun/quality/command.rb +84 -0
  39. data/lib/polyrun/quality/measure.rb +38 -0
  40. data/lib/polyrun/quality/observe.rb +53 -0
  41. data/lib/polyrun/quality/observe_hook.rb +103 -0
  42. data/lib/polyrun/quality/sandbox.rb +70 -0
  43. data/lib/polyrun/rspec_support.rb +1 -1
  44. data/lib/polyrun/spec_quality/config.rb +8 -3
  45. data/lib/polyrun/spec_quality.rb +3 -4
  46. data/lib/polyrun/version.rb +1 -1
  47. data/polyrun.gemspec +1 -1
  48. data/sig/polyrun/config.rbs +2 -2
  49. metadata +29 -1
@@ -1,3 +1,5 @@
1
+ require_relative "tool_defaults"
2
+
1
3
  module Polyrun
2
4
  class Config
3
5
  # Lightweight top-level key checks for +polyrun validate+.
@@ -11,9 +13,11 @@ module Polyrun
11
13
  start
12
14
  hooks
13
15
  reporting
14
- workers
15
16
  suites
16
- ].freeze
17
+ graph
18
+ mutation
19
+ quality
20
+ ].concat(ToolDefaults::SHARED.keys).freeze
17
21
 
18
22
  module_function
19
23
 
@@ -27,7 +31,8 @@ module Polyrun
27
31
 
28
32
  unknown = raw.keys.map(&:to_s) - KNOWN_TOP_LEVEL
29
33
  messages = unknown.sort.map { |k| "polyrun validate: unknown top-level key #{k.inspect}" }
30
- {ok: messages.empty?, messages: messages}
34
+ messages.concat(Polyrun::Config::Tools.validate(raw).map { |message| "polyrun validate: #{message}" })
35
+ {ok: messages.empty?, messages: messages.uniq}
31
36
  end
32
37
  end
33
38
  end
@@ -1,3 +1,5 @@
1
+ require_relative "tools"
2
+
1
3
  module Polyrun
2
4
  class Config
3
5
  # Applies a named +suites:+ overlay onto a loaded polyrun.yml hash.
@@ -8,7 +10,7 @@ module Polyrun
8
10
  shard_workers workers_per_shard
9
11
  ].freeze
10
12
 
11
- TOP_MERGE_KEYS = %w[workers prepare start hooks reporting coverage databases].freeze
13
+ TOP_MERGE_KEYS = (%w[prepare start hooks reporting coverage databases graph mutation quality] + ToolDefaults::SHARED.keys).freeze
12
14
 
13
15
  module_function
14
16
 
@@ -33,6 +35,9 @@ module Polyrun
33
35
  end
34
36
 
35
37
  def apply_overlay!(base, overlay)
38
+ errors = Tools.validate(overlay)
39
+ raise Polyrun::Error, errors.join("; ") unless errors.empty?
40
+
36
41
  merge_partition_block!(base, overlay)
37
42
  merge_partition_shortcuts!(base, overlay)
38
43
  merge_top_keys!(base, overlay)
@@ -0,0 +1,42 @@
1
+ module Polyrun
2
+ class Config
3
+ module ToolDefaults
4
+ STAGING = {"max_bytes" => 67_108_864, "max_files" => 10_000,
5
+ "exclude" => %w[vendor node_modules tmp log pkg benchmarks],
6
+ "exclude_paths" => %w[coverage], "include_hidden" => %w[.rspec .ruby-version]}.freeze
7
+ COMMON = {"enabled" => false, "root" => nil, "workers" => 1, "timeout" => 300,
8
+ "command" => [], "output" => nil, "max_output_bytes" => 1_048_576,
9
+ "max_input_bytes" => 1_048_576, "max_artifact_bytes" => 67_108_864,
10
+ "source_roots" => %w[lib app], "source_fallback" => true,
11
+ "source_exclude" => %w[spec test features examples benchmarks vendor node_modules tmp log coverage pkg],
12
+ "max_nodes" => 250_000, "max_source_files" => 100_000, "max_source_file_bytes" => 10_485_760,
13
+ "max_source_bytes" => 67_108_864, "staging" => STAGING}.freeze
14
+ SHARED = COMMON.except("enabled").freeze
15
+ GRAPH = {"timeout" => 60, "state_dir" => ".polyrun/graph", "json" => false,
16
+ "calls" => false, "callers" => false, "callees" => false, "control_plane" => false, "prove" => false,
17
+ "max_operations" => 1000, "max_diff_bytes" => 524_288,
18
+ "max_plan_bytes" => 1_048_576, "max_receipt_files" => 100_000}.freeze
19
+ MUTATION = {"max_workers" => 32, "max_mutations" => 1000, "max_subjects" => 10_000,
20
+ "max_report_bytes" => 16_777_216, "max_copy_bytes" => 1_073_741_824,
21
+ "operators" => %w[literal operator body], "subjects" => [], "subjects_file" => nil,
22
+ "observed" => [], "plan" => nil, "shard" => 1, "total" => 1}.freeze
23
+ OBSERVE = {"max_entries" => 10_000, "max_artifact_bytes" => 16_777_216}.freeze
24
+ MEASURE = {"label" => "command", "ceilings" => {}}.freeze
25
+ EXECUTION = %w[enabled root timeout command output max_output_bytes].freeze
26
+ FEATURES = {"graph" => GRAPH, "mutation" => MUTATION, "observe" => OBSERVE, "measure" => MEASURE}.freeze
27
+
28
+ module_function
29
+
30
+ def for(feature)
31
+ feature = feature.to_s
32
+ common = case feature
33
+ when "graph" then COMMON.except("workers")
34
+ when "observe" then COMMON.slice(*EXECUTION, "max_artifact_bytes")
35
+ when "measure" then COMMON.slice(*EXECUTION)
36
+ else COMMON
37
+ end
38
+ Marshal.load(Marshal.dump(common.merge(FEATURES.fetch(feature))))
39
+ end
40
+ end
41
+ end
42
+ end
@@ -0,0 +1,79 @@
1
+ require_relative "tool_defaults"
2
+
3
+ module Polyrun
4
+ class Config
5
+ module ToolValidation
6
+ OPTIONAL_STRINGS = %w[root output subjects_file plan].freeze
7
+ COUNTS = %w[min_line_churn min_query_count hot_line_example_overlap minimum_unique_lines_per_example max_zero_hit_examples max_hot_line_overlap].freeze
8
+
9
+ module_function
10
+
11
+ def check(value, defaults, prefix)
12
+ return ["#{prefix} must be a mapping"] unless value.is_a?(Hash)
13
+
14
+ value.flat_map do |key, item|
15
+ path = "#{prefix}.#{key}"
16
+ next ["unknown setting #{path}"] unless defaults.key?(key)
17
+ expected = defaults[key]
18
+ if expected.is_a?(Hash)
19
+ (key == "ceilings") ? check_ceilings(item, path) : check(item, expected, path)
20
+ elsif valid?(key, item, expected)
21
+ []
22
+ else
23
+ ["invalid setting #{path}"]
24
+ end
25
+ end
26
+ end
27
+
28
+ def valid?(key, value, expected)
29
+ return value.nil? || valid_string?(value) if OPTIONAL_STRINGS.include?(key)
30
+ return value.is_a?(Numeric) && value.finite? && value.positive? if key == "timeout"
31
+ return relative_path?(value) if key == "state_dir"
32
+ return valid_count?(value, expected) if COUNTS.include?(key)
33
+ return value.nil? || nonnegative?(value) if expected.nil?
34
+ return positive_integer?(value) if expected.is_a?(Integer)
35
+ return nonnegative?(value) && value <= 1 if key == "sample"
36
+ return value == true || value == false if expected == true || expected == false
37
+ return valid_array?(key, value) if expected.is_a?(Array)
38
+
39
+ valid_string?(value)
40
+ end
41
+
42
+ def positive_integer?(value)
43
+ value.is_a?(Integer) && value.positive?
44
+ end
45
+
46
+ def valid_count?(value, expected)
47
+ (expected.nil? && value.nil?) || (value.is_a?(Integer) && value >= 0)
48
+ end
49
+
50
+ def valid_string?(value)
51
+ value.is_a?(String) && !value.empty? && !value.include?("\0")
52
+ end
53
+
54
+ def nonnegative?(value)
55
+ value.is_a?(Numeric) && value.finite? && value >= 0
56
+ end
57
+
58
+ def valid_array?(key, value)
59
+ return false unless value.is_a?(Array) && value.all? { |entry| valid_string?(entry) }
60
+ return !value.empty? && (value - %w[literal operator body]).empty? if key == "operators"
61
+ return value.all? { |entry| relative_path?(entry) || entry == "." } if key == "source_roots"
62
+
63
+ true
64
+ end
65
+
66
+ def relative_path?(value)
67
+ value.is_a?(String) && !value.empty? && !value.include?("\0") && !value.split("/", -1).any? { |part| ["", ".", ".."].include?(part) }
68
+ end
69
+
70
+ def check_ceilings(value, prefix)
71
+ return ["#{prefix} must be a mapping"] unless value.is_a?(Hash)
72
+
73
+ value.filter_map do |key, item|
74
+ "invalid setting #{prefix}.#{key}" unless item.is_a?(Numeric) && item.finite? && item >= 0
75
+ end
76
+ end
77
+ end
78
+ end
79
+ end
@@ -0,0 +1,120 @@
1
+ require_relative "tool_validation"
2
+
3
+ module Polyrun
4
+ class Config
5
+ module Tools
6
+ module_function
7
+
8
+ def merge(base, overlay)
9
+ base.merge(overlay) { |_, before, after| (before.is_a?(Hash) && after.is_a?(Hash)) ? merge(before, after) : after }
10
+ end
11
+
12
+ def runtime(feature, settings = {})
13
+ raise ArgumentError, "settings must be a mapping" unless settings.is_a?(Hash)
14
+
15
+ value = merge(ToolDefaults.for(feature), stringify(settings))
16
+ errors = ToolValidation.check(value, ToolDefaults.for(feature), feature.to_s)
17
+ raise ArgumentError, errors.join("; ") unless errors.empty?
18
+
19
+ value
20
+ end
21
+
22
+ def resolve(cfg, feature, overrides: {}, env: ENV, root: Dir.pwd)
23
+ errors = validate(cfg.raw)
24
+ raise ArgumentError, errors.join("; ") unless errors.empty?
25
+
26
+ raw = stringify(cfg.raw)
27
+ defaults = ToolDefaults.for(feature)
28
+ shared = shared_defaults(raw).slice(*defaults.keys)
29
+ value = merge(merge(defaults, shared), feature_config(raw, feature))
30
+ value = merge(value, environment(feature, env))
31
+ value = runtime(feature, merge(value, stringify(overrides)))
32
+ normalize_paths(value, root)
33
+ end
34
+
35
+ def shared_defaults(raw)
36
+ shared = raw.slice(*ToolDefaults::SHARED.keys)
37
+ if shared["workers"].is_a?(String)
38
+ shared["workers"] = Integer(shared["workers"], exception: false) || shared["workers"]
39
+ end
40
+ shared
41
+ end
42
+
43
+ def normalize_paths(value, root)
44
+ value["root"] = File.expand_path(value["root"] || root, root)
45
+ %w[output subjects_file].each { |key| value[key] = File.expand_path(value[key], value["root"]) if value[key] }
46
+ value
47
+ end
48
+
49
+ def feature_config(raw, feature)
50
+ return raw.fetch(feature, {}) unless %w[observe measure].include?(feature)
51
+
52
+ quality = raw.fetch("quality", {})
53
+ merge(quality.slice(*ToolDefaults.for(feature).keys), quality.fetch(feature, {}))
54
+ end
55
+
56
+ def environment(feature, env)
57
+ result = {}
58
+ applicable = ToolDefaults.for(feature)
59
+ {"workers" => "POLYRUN_WORKERS", "timeout" => "POLYRUN_TIMEOUT", "max_output_bytes" => "POLYRUN_MAX_OUTPUT_BYTES"}.each do |key, name|
60
+ next if !applicable.key?(key) || env[name].nil? || env[name].empty?
61
+
62
+ result[key] = (key == "timeout") ? Float(env[name]) : Integer(env[name])
63
+ end
64
+ name = "POLYRUN_#{%w[observe measure].include?(feature) ? "QUALITY" : feature.upcase}"
65
+ if env.key?(name)
66
+ raise ArgumentError, "invalid #{name}" unless %w[1 true yes on 0 false no off].include?(env[name].downcase)
67
+
68
+ result["enabled"] = %w[1 true yes on].include?(env[name].downcase)
69
+ end
70
+ result
71
+ end
72
+
73
+ def validate(raw)
74
+ raw = stringify(raw)
75
+ errors = ToolValidation.check(shared_defaults(raw), ToolDefaults::SHARED, "config")
76
+ errors << 'unknown top-level key "global"' if raw.key?("global")
77
+ %w[graph mutation].each do |feature|
78
+ errors.concat(ToolValidation.check(raw[feature], ToolDefaults.for(feature), feature)) if raw.key?(feature)
79
+ end
80
+ errors.concat(validate_quality(raw["quality"])) if raw.key?("quality")
81
+ errors
82
+ end
83
+
84
+ def validate_quality(quality)
85
+ return ["quality must be a mapping"] unless quality.is_a?(Hash)
86
+
87
+ errors = ToolValidation.check(quality.except("observe", "measure", "spec_quality"), ToolDefaults::COMMON.slice(*ToolDefaults::EXECUTION, "max_artifact_bytes"), "quality")
88
+ %w[observe measure].each do |feature|
89
+ errors.concat(ToolValidation.check(quality[feature], ToolDefaults.for(feature), "quality.#{feature}")) if quality.key?(feature)
90
+ end
91
+ if quality.key?("spec_quality")
92
+ require_relative "../spec_quality/config"
93
+ defaults = SpecQuality::Config::DEFAULTS.merge("enabled" => false)
94
+ errors.concat(ToolValidation.check(quality["spec_quality"], defaults, "quality.spec_quality"))
95
+ end
96
+ errors
97
+ end
98
+
99
+ def spec_quality(root:, env: ENV)
100
+ cfg = Config.load(path: env["POLYRUN_CONFIG"], root: root, suite: env["POLYRUN_SUITE"])
101
+ errors = validate(cfg.raw)
102
+ raise ArgumentError, errors.join("; ") unless errors.empty?
103
+
104
+ raw = stringify(cfg.raw)
105
+ shared = shared_defaults(raw)
106
+ settings = {}
107
+ settings["track_under"] = shared["source_roots"] if shared.key?("source_roots")
108
+ merge(settings, raw.fetch("quality", {}).fetch("spec_quality", {}))
109
+ end
110
+
111
+ def stringify(value)
112
+ case value
113
+ when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
114
+ when Array then value.map { |item| stringify(item) }
115
+ else value
116
+ end
117
+ end
118
+ end
119
+ end
120
+ end
@@ -11,9 +11,9 @@ module Polyrun
11
11
 
12
12
  attr_reader :path, :raw, :suite
13
13
 
14
- def self.load(path: nil, suite: nil)
14
+ def self.load(path: nil, suite: nil, root: Dir.pwd)
15
15
  explicit = path && !path.to_s.strip.empty?
16
- resolved = resolve_path(path)
16
+ resolved = resolve_path(path, root: root)
17
17
  if explicit && !(resolved && File.file?(resolved))
18
18
  raise Polyrun::Error, "polyrun config not found: #{path}"
19
19
  end
@@ -32,11 +32,11 @@ module Polyrun
32
32
  new(path: resolved, raw: merged, suite: applied)
33
33
  end
34
34
 
35
- def self.resolve_path(explicit)
35
+ def self.resolve_path(explicit, root: Dir.pwd)
36
36
  return File.expand_path(explicit) if explicit && !explicit.empty?
37
37
 
38
38
  DEFAULT_FILENAMES.each do |name|
39
- full = File.expand_path(name, Dir.pwd)
39
+ full = File.expand_path(name, root)
40
40
  return full if File.file?(full)
41
41
  end
42
42
  nil
@@ -93,3 +93,5 @@ require_relative "config/suite"
93
93
  require_relative "config/resolver"
94
94
  require_relative "config/effective"
95
95
  require_relative "config/schema"
96
+
97
+ require_relative "config/tools"
@@ -0,0 +1,64 @@
1
+ require "fileutils"
2
+ require_relative "plan"
3
+ require_relative "../quality/command"
4
+ require "rbconfig"
5
+ require_relative "../quality/sandbox"
6
+
7
+ module Polyrun
8
+ module Graph
9
+ class Client
10
+ def initialize(root: Dir.pwd, timeout: nil, settings: {})
11
+ @settings = Config::Tools.runtime("graph", settings.merge(timeout ? {"timeout" => timeout} : {}))
12
+ @root = File.realpath(root)
13
+ library = File.expand_path("../..", __dir__)
14
+ @command = [RbConfig.ruby, "-I", library, "-rpolyrun/graph/worker", "-e", "exit Polyrun::Graph::Worker.run(ARGV)", "--"]
15
+ @timeout = @settings["timeout"]
16
+ end
17
+
18
+ def call(arguments, prove: [])
19
+ state = Workspace.new(@root, settings: @settings).path(@settings["state_dir"])
20
+
21
+ FileUtils.mkdir_p(state)
22
+ lock_path = File.join(state, "polyrun.lock")
23
+ raise Error.new("INVALID_PLAN", "symbolic link in lock path") if File.symlink?(lock_path)
24
+
25
+ File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
26
+ raise Error.new("WORKSPACE_BUSY", "another graph command is running") unless lock.flock(File::LOCK_EX | File::LOCK_NB)
27
+
28
+ dispatch(arguments, prove)
29
+ end
30
+ end
31
+
32
+ private
33
+
34
+ def dispatch(arguments, prove)
35
+ verb, id = arguments.reject { |argument| argument == "--json" }
36
+ return check(Plan.new(@root, id, settings: @settings), arguments, prove) if verb == "check"
37
+
38
+ invoke(arguments)
39
+ end
40
+
41
+ def invoke(arguments)
42
+ Quality::Command.call(@command + arguments, root: @root, timeout: @timeout, max_output: @settings["max_output_bytes"], env: {"POLYRUN_GRAPH_ROOT" => @root, "POLYRUN_GRAPH_SETTINGS" => JSON.generate(@settings), "RUBYOPT" => nil})
43
+ end
44
+
45
+ def check(plan, arguments, prove)
46
+ checked = false
47
+ plan.invalidate!
48
+ result = invoke(arguments)
49
+ return result unless result["exitstatus"].zero?
50
+
51
+ plan.record_check!
52
+ prove_result = prove.empty? ? nil : Quality::Command.call(prove, root: plan.tree, timeout: @timeout, max_output: @settings["max_output_bytes"], env: Quality::Sandbox.environment(plan.tree))
53
+ if prove_result && !prove_result["exitstatus"].zero?
54
+ raise Error.new("PROVE_FAILED", "prove command failed: #{prove_result["stderr"]}", exitstatus: prove_result["exitstatus"])
55
+ end
56
+ plan.verify!
57
+ checked = true
58
+ result
59
+ ensure
60
+ plan.invalidate! unless checked
61
+ end
62
+ end
63
+ end
64
+ end
@@ -0,0 +1,13 @@
1
+ module Polyrun
2
+ module Graph
3
+ class Error < StandardError
4
+ attr_reader :code, :exitstatus
5
+
6
+ def initialize(code, message, exitstatus: 1)
7
+ @code = code
8
+ @exitstatus = exitstatus
9
+ super(message)
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,75 @@
1
+ require_relative "workspace"
2
+ require_relative "syntax"
3
+
4
+ module Polyrun
5
+ module Graph
6
+ class Index
7
+ def initialize(root, settings: {})
8
+ @workspace = Workspace.new(root, settings: settings)
9
+ end
10
+
11
+ def call
12
+ hashes = @workspace.hashes
13
+ snapshot = @workspace.snapshot(hashes)
14
+ existing = cached_index(snapshot)
15
+ return existing if existing
16
+
17
+ methods = []
18
+ calls = []
19
+ hashes.each_key do |relative|
20
+ syntax = Syntax.new(relative, File.binread(@workspace.path(relative)), max_nodes: @workspace.settings["max_nodes"]).parse
21
+ methods.concat(syntax.methods)
22
+ calls.concat(syntax.calls)
23
+ enforce_node_limit!(methods.size + calls.size)
24
+ end
25
+ raise Error.new("STALE_SNAPSHOT", "source changed while indexing") unless @workspace.hashes == hashes
26
+
27
+ edges = resolve(methods, calls)
28
+ @workspace.write_json("#{@workspace.state}/index.json", {"format" => 1, "snapshot" => snapshot,
29
+ "files" => hashes, "methods" => methods, "calls" => calls, "edges" => edges, "reused" => false})
30
+ end
31
+
32
+ def load
33
+ value = @workspace.read_json("#{@workspace.state}/index.json")
34
+ unless value.is_a?(Hash) && value["format"] == 1 && %w[methods calls edges].all? { |key| value[key].is_a?(Array) }
35
+ raise Error.new("INVALID_PLAN", "invalid graph index")
36
+ end
37
+ value
38
+ end
39
+
40
+ private
41
+
42
+ def cached_index(snapshot)
43
+ return unless File.file?(@workspace.path("#{@workspace.state}/index.json"))
44
+
45
+ existing = load
46
+ return unless existing["snapshot"] == snapshot
47
+
48
+ enforce_node_limit!(existing["methods"].size + existing["calls"].size)
49
+ existing.merge("reused" => true)
50
+ end
51
+
52
+ def enforce_node_limit!(count)
53
+ raise Error.new("RESOURCE_LIMIT", "too many graph nodes") if count > @workspace.settings["max_nodes"]
54
+ end
55
+
56
+ def resolve(methods, calls)
57
+ lookup = methods.group_by { |method| [method["owner"], method["scope"], method["name"]] }
58
+ calls.filter_map do |call|
59
+ owner, scope = if call["receiver"].nil? || call["receiver"] == "self"
60
+ [call["owner"], call["scope"]]
61
+ else
62
+ [call["receiver"].delete_prefix("::"), "singleton"]
63
+ end
64
+ candidates = owner && lookup[[owner, scope, call["name"]]]
65
+ target = candidates&.one? ? candidates.first : nil
66
+ call["target"] = target && target["id"]
67
+ call["target_provenance"] = target ? "static_guess" : "unknown"
68
+ next unless target && call["method_id"]
69
+
70
+ {"from_id" => call["method_id"], "to_id" => target["id"], "call_id" => call["id"], "provenance" => "static_guess"}
71
+ end
72
+ end
73
+ end
74
+ end
75
+ end
@@ -0,0 +1,58 @@
1
+ require_relative "index"
2
+
3
+ module Polyrun
4
+ module Graph
5
+ class Inspect
6
+ def initialize(index)
7
+ @index = index
8
+ end
9
+
10
+ def call(selector, flags)
11
+ return control_plane if flags.include?("--control-plane")
12
+
13
+ methods = select_methods(selector)
14
+ raise Error.new("UNKNOWN_TARGET", "no matching method") if methods.empty?
15
+ raise Error.new("AMBIGUOUS_NODE", "choose a method owner or source path") unless methods.one?
16
+
17
+ nodes = methods.map do |method|
18
+ value = method.dup
19
+ value["calls"] = @index["calls"].select { |node| node["method_id"] == method["id"] } if flags.include?("--calls")
20
+ %w[callers callees].each do |direction|
21
+ next unless flags.include?("--#{direction}")
22
+
23
+ value[direction] = connections(method, direction)
24
+ end
25
+ value
26
+ end
27
+ {"ok" => true, "snapshot" => @index["snapshot"], "nodes" => nodes}
28
+ end
29
+
30
+ private
31
+
32
+ def connections(method, direction)
33
+ lookup = @index["methods"].to_h { |entry| [entry["id"], entry] }
34
+ from, to = (direction == "callers") ? %w[to_id from_id] : %w[from_id to_id]
35
+ @index["edges"].select { |edge| edge[from] == method["id"] }.map do |edge|
36
+ lookup.fetch(edge[to]).merge("provenance" => edge["provenance"])
37
+ end
38
+ end
39
+
40
+ def select_methods(selector)
41
+ if selector&.start_with?("path:")
42
+ path, name = selector.delete_prefix("path:").split("#", 2)
43
+ @index["methods"].select { |method| method["path"] == path && (!name || method["name"] == name) }
44
+ else
45
+ @index["methods"].select { |method| [method["id"], method["subject"], method["name"]].include?(selector) }
46
+ end
47
+ end
48
+
49
+ def control_plane
50
+ lifecycle = @index["methods"].select { |method| method["name"].match?(/\A(?:start|stop|shutdown|run|perform|call|process|poll|tick|schedule)[!?]?\z/) }
51
+ signals = @index["calls"].select { |node| node["name"].match?(/\A(?:notify|broadcast|signal|enqueue|publish|perform_async)[!?]?\z/) }
52
+ signal_ids = signals.to_h { |node| [node["id"], true] }
53
+ {"ok" => true, "snapshot" => @index["snapshot"], "control_plane" => {"lifecycle" => lifecycle,
54
+ "signals" => signals, "signal_edges" => @index["edges"].select { |edge| signal_ids[edge["call_id"]] }}}
55
+ end
56
+ end
57
+ end
58
+ end
@@ -0,0 +1,134 @@
1
+ require "json"
2
+ require "digest"
3
+ require "find"
4
+ require_relative "error"
5
+ require_relative "workspace"
6
+ require "prism"
7
+ require_relative "transaction"
8
+
9
+ module Polyrun
10
+ module Graph
11
+ class Plan
12
+ attr_reader :tree, :directory
13
+
14
+ def initialize(root, id, settings: {})
15
+ raise Error.new("INVALID_PLAN", "invalid plan id") unless id.is_a?(String) && id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}\z/)
16
+
17
+ @settings = Config::Tools.runtime("graph", settings)
18
+ @root = File.realpath(root)
19
+ @directory = safe_path(@root, "#{@settings["state_dir"]}/plans/#{id}")
20
+ @tree = safe_path(@directory, "tree")
21
+ end
22
+
23
+ def metadata
24
+ read_json(safe_path(@directory, "meta.json"))
25
+ end
26
+
27
+ def verify!
28
+ receipt = read_json(safe_path(@directory, "polyrun-check.json"))
29
+ raise Error.new("CHECK_FAILED", "plan changed since check") unless receipt == fingerprint
30
+
31
+ verify_originals!
32
+ true
33
+ end
34
+
35
+ def record_check!
36
+ check = read_json(safe_path(@directory, "check.json"))
37
+ raise Error.new("CHECK_FAILED", "graph check did not succeed") unless check["status"] == "ok"
38
+
39
+ verify_originals!
40
+ receipt = JSON.generate(fingerprint)
41
+ raise Error.new("RESOURCE_LIMIT", "plan receipt is too large") if receipt.bytesize > @settings["max_plan_bytes"]
42
+
43
+ File.write(safe_path(@directory, "polyrun-check.json"), receipt)
44
+ end
45
+
46
+ def invalidate!
47
+ %w[check.json polyrun-check.json].each do |name|
48
+ path = safe_path(@directory, name)
49
+ File.unlink(path) if File.exist?(path)
50
+ end
51
+ end
52
+
53
+ def verify_originals!
54
+ hashes = metadata.fetch("pre_hashes")
55
+ raise Error.new("INVALID_PLAN", "invalid original file hashes") unless hashes.is_a?(Hash) && !hashes.empty?
56
+
57
+ hashes.each do |relative, expected|
58
+ path = safe_path(@root, relative)
59
+ staged = safe_path(@tree, relative)
60
+ raise Error.new("INVALID_PLAN", "staged file missing: #{relative}") unless File.file?(staged)
61
+ unless File.file?(path) && Digest::SHA256.file(path).hexdigest == expected
62
+ raise Error.new("STALE_SNAPSHOT", "file changed before apply: #{relative}")
63
+ end
64
+ end
65
+ raise Error.new("STALE_SNAPSHOT", "source file inventory changed") unless Workspace.new(@root, settings: @settings).files == hashes.keys.sort
66
+ end
67
+
68
+ def check!
69
+ verify_originals!
70
+ metadata.fetch("pre_hashes").each_key do |relative|
71
+ path = safe_path(@tree, relative)
72
+ raise Error.new("PARSE_FAILED", "invalid staged Ruby: #{relative}") if Prism.parse_file(path).failure?
73
+ expected = metadata.fetch("staged_hashes").fetch(relative)
74
+ raise Error.new("CHECK_FAILED", "staged operation changed: #{relative}") unless Digest::SHA256.file(path).hexdigest == expected
75
+ end
76
+ result = {"ok" => true, "status" => "ok", "provenance" => "syntax"}
77
+ File.write(safe_path(@directory, "check.json"), JSON.generate(result))
78
+ result
79
+ end
80
+
81
+ def apply!
82
+ transaction = Transaction.new(@root, @directory, settings: @settings)
83
+ transaction.recover!
84
+ verify!
85
+ replacements = metadata.fetch("pre_hashes").keys.filter_map do |relative|
86
+ original = safe_path(@root, relative)
87
+ staged = safe_path(@tree, relative)
88
+ [relative, File.binread(original), File.binread(staged)] if Digest::SHA256.file(original).hexdigest != Digest::SHA256.file(staged).hexdigest
89
+ end
90
+ transaction.commit(replacements)
91
+ end
92
+
93
+ private
94
+
95
+ def fingerprint
96
+ files = {}
97
+ Find.find(@tree) do |path|
98
+ raise Error.new("INVALID_PLAN", "symbolic link in plan tree") if File.symlink?(path)
99
+ next if File.directory?(path)
100
+ raise Error.new("INVALID_PLAN", "nonregular file in plan tree") unless File.file?(path)
101
+ raise Error.new("INVALID_PLAN", "too many plan files") if files.length >= @settings["max_receipt_files"]
102
+
103
+ files[path.delete_prefix("#{@tree}/")] = Digest::SHA256.file(path).hexdigest
104
+ end
105
+ {"metadata" => Digest::SHA256.file(safe_path(@directory, "meta.json")).hexdigest, "files" => files}
106
+ end
107
+
108
+ def safe_path(base, relative)
109
+ parts = relative.is_a?(String) ? relative.split("/", -1) : []
110
+ if parts.empty? || parts.any? { |part| part.empty? || part == "." || part == ".." } || relative.include?("\0")
111
+ raise Error.new("INVALID_PLAN", "invalid plan path")
112
+ end
113
+ parts.reduce(base) do |parent, part|
114
+ path = File.join(parent, part)
115
+ raise Error.new("INVALID_PLAN", "symbolic link in plan path") if File.symlink?(path)
116
+
117
+ path
118
+ end
119
+ end
120
+
121
+ def read_json(path)
122
+ raise Error.new("CHECK_FAILED", "check or plan metadata missing") unless File.file?(path)
123
+ raise Error.new("INVALID_PLAN", "plan metadata too large") if File.size(path) > @settings["max_plan_bytes"]
124
+
125
+ value = JSON.parse(File.binread(path))
126
+ raise Error.new("INVALID_PLAN", "plan metadata must be an object") unless value.is_a?(Hash)
127
+
128
+ value
129
+ rescue JSON::ParserError => e
130
+ raise Error.new("INVALID_PLAN", e.message)
131
+ end
132
+ end
133
+ end
134
+ end