archsight 0.3.3 → 0.4.0

data/lib/archsight/cli.rb

@@ -52,8 +52,8 @@ module Archsight
     private
 
     def load_handlers
-      handlers_dir = File.expand_path("import/handlers", __dir__)
-      Dir.glob(File.join(handlers_dir, "*.rb")).each { |f| require f }
+      require "archsight/import"
+      Archsight::Import::HandlerLoader.load_builtin!
     end
 
     def resolve_handler(path, language)
@@ -133,6 +133,12 @@ module Archsight
         warnings.each { |warning| puts "  #{warning}" }
       end
 
+      structure = linter.structural_warnings
+      if structure.any?
+        puts "Modeling warnings (#{structure.count}):"
+        structure.each { |warning| puts "  #{warning}" }
+      end
+
       if errors.any?
         puts "Validation Errors (#{errors.count}):"
         errors.each { |error| display_error_with_context(error) }
@@ -172,15 +178,18 @@ module Archsight
     option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Show execution plan without running"
     option :filter, aliases: "-f", type: :string, desc: "Filter imports by name (regex pattern)"
     option :force, aliases: "-F", type: :boolean, default: false, desc: "Ignore cache and re-run all imports"
+    option :deps, type: :boolean, default: true,
+                  desc: "With -f, also run the imports the matched ones depend on (--no-deps: only the matched ones)"
+    option :lint, type: :boolean, default: false, desc: "Validate the resources after the run (like archsight lint)"
     def import
       configure_resources
       require "archsight/database"
-      require "archsight/import/executor"
+      require "archsight/import"
 
       resources_dir = Archsight.resources_dir
 
-      # Load all handlers
-      require_import_handlers
+      # Built-in handlers; the executor loads the handlers of the resources repository (import/handlerPath)
+      Archsight::Import::HandlerLoader.load_builtin!
 
       # Create database that loads from resources directory
       # Only load the kinds that import handlers inspect at runtime (ApplicationComponent
@@ -199,7 +208,8 @@ module Archsight
           resources_dir: resources_dir,
           verbose: true,
           filter: options[:filter],
-          force: options[:force]
+          force: options[:force],
+          deps: options[:deps]
         )
         executor.execution_plan
       else
@@ -208,10 +218,12 @@ module Archsight
           resources_dir: resources_dir,
           verbose: options[:verbose],
           filter: options[:filter],
-          force: options[:force]
+          force: options[:force],
+          deps: options[:deps]
         )
         executor.run!
         puts "All imports completed successfully."
+        lint_after_import if options[:lint]
       end
     rescue Archsight::Import::InterruptedError
       # Graceful shutdown already handled by executor
@@ -231,6 +243,11 @@ module Archsight
     option :verbose, aliases: "-v", type: :boolean, default: false, desc: "Verbose output"
     option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "List analyses without running"
     option :filter, aliases: "-f", type: :string, desc: "Filter analyses by name (regex pattern)"
+    option :format, type: :string, default: "terminal", enum: %w[terminal typst],
+                    desc: "Output format: terminal rendering or Typst source (https://typst.app)"
+    option :output, aliases: "-o", type: :string, desc: "Write the Typst source to this file instead of stdout"
+    option :template, type: :string,
+                      desc: "Typst file to import for the layout; it must define archsight-report and analysis-result"
     def analyze
       configure_resources
       require "archsight/database"
@@ -243,7 +260,7 @@ module Archsight
       return print_analysis_dry_run(analyses) if options[:dry_run]
 
       results = execute_analyses(db, analyses)
-      print_analysis_results(results)
+      options[:format] == "typst" ? write_analysis_typst(results) : print_analysis_results(results)
       exit 1 if results.any?(&:failed?)
     end
 
@@ -253,7 +270,8 @@ module Archsight
     end
 
     desc "diagram INPUT...", "Render .asd diagram files to SVG"
-    long_desc "Renders each INPUT.asd to an SVG next to it (or to --output for a single input)."
+    long_desc "Renders each INPUT.asd to an SVG next to it (or to --output for a single input). " \
+              "With --format, re-indents the inputs in place instead (--check: only report the ones that are not formatted)."
     option :output, aliases: "-o", type: :string, desc: "SVG output path (single input file only)"
     option :watch, aliases: "-w", type: :boolean, desc: "Re-render whenever an input file changes"
     option :relation, type: :string, desc: "Edge relations to draw: comma-separated list, or 'all' (default: dependency,implements)"
@@ -261,6 +279,8 @@ module Archsight
     option :theme, type: :string, desc: "Spacing/font-size theme (default: the file's own `theme` statement)"
     option :legend, type: :string, desc: "Legend placement (default: the file's own `legend` statement, else auto)"
     option :profile, aliases: "-p", type: :boolean, desc: "Print stage timing stats after each render"
+    option :format, type: :boolean, desc: "Re-indent the inputs in place instead of rendering them (-o: write a single input there)"
+    option :check, type: :boolean, desc: "With --format: only list the inputs that are not formatted, exit 1 if any"
     def diagram(*inputs)
       require "archsight/diagram/cli"
 
@@ -275,6 +295,7 @@ module Archsight
 
       status = diagram::CLI.new.run_with(
         inputs: inputs, output: options[:output], watch: options[:watch], profile: options[:profile],
+        format: options[:format], check: options[:check],
         style: options[:style], theme: options[:theme], legend: options[:legend],
         relation_filter: if relation.nil?
                            diagram::Relations::DEFAULT_FILTER
@@ -288,7 +309,7 @@ module Archsight
     desc "export [PAGE...]", "Export wiki pages to another system"
     long_desc <<~DESC
       Publishes wiki pages to the system named by --to. With no PAGE, every page that links to a target
-      page (for confluence: `confluence: <page URL>` in its frontmatter) is exported. --tag TAG limits the export to pages carrying one of the given tags.
+      page (for confluence: `links: { confluence: <page URL> }` in its frontmatter) is exported. --tag TAG limits the export to pages carrying one of the given tags.
 
       confluence: a page is only overwritten when Confluence still holds what the last export wrote. Pages
       never exported before, or edited in Confluence since, are reported as blocked and not exported until
@@ -348,18 +369,78 @@ module Archsight
       results.each { |r| puts "#{labels.fetch(r.status).ljust(width)}  #{r.page}: #{r.message}" }
       counts = results.group_by(&:status).transform_values(&:count)
       puts counts.map { |status, count| "#{count} #{labels.fetch(status)}" }.join(", ") unless results.empty?
-      puts "Nothing to export: no page has a `confluence:` link." if results.empty?
+      puts "Nothing to export: no page has a `confluence` link." if results.empty?
     end
 
-    def configure_resources
-      Archsight.resources_dir = options[:resources] if options[:resources]
+    # `archsight import --lint`: validate the whole model after the run. A resource with an error that an import
+    # generated names that import, so a dangling reference shows up with the import that caused it.
+    def lint_after_import
+      require "archsight/linter"
+      require "archsight/helpers"
+
+      db = Archsight::Database.new(Archsight.resources_dir, compute_annotations: false)
+      begin
+        db.reload!
+      rescue Archsight::ResourceError => e
+        # a relation to a resource that does not exist stops the load: name the import of the resource it is in
+        display_error_with_context("#{e}#{generated_by_note(producer_at(e.ref))}")
+        exit 1
+      end
+      errors = Archsight::Linter.new(db).validate
+      if errors.empty?
+        puts "All validations passed!"
+        return
+      end
+
+      puts "Validation Errors (#{errors.count}):"
+      errors.each { |error| display_error_with_context(with_generating_import(db, error)) }
+      exit 1
+    end
+
+    # Add "(generated by Import:X)" to a lint error at a location an import wrote
+    def with_generating_import(db, error)
+      path, line_no = error.match(/\A(.+?):(\d+): /)&.captures
+      return error unless path
+
+      "#{error}#{generated_by_note(producer_of(db, path, line_no.to_i))}"
     end
 
-    def require_import_handlers
-      handlers_dir = File.expand_path("import/handlers", __dir__)
-      Dir.glob(File.join(handlers_dir, "*.rb")).each do |handler_file|
-        require handler_file
+    # The import that a load error (a relation to a resource that does not exist) comes from, read without resolving
+    # relations
+    def producer_at(ref)
+      return nil unless ref.respond_to?(:path)
+
+      db = Archsight::Database.new(Archsight.resources_dir, compute_annotations: false, verify: false)
+      db.reload!
+      producer_of(db, ref.path, ref.line_no)
+    rescue Archsight::ResourceError
+      nil
+    end
+
+    # The import a resource at a file location comes from: its `generated/script`, else the import whose output file
+    # it is in (a command writes its documents unmarked)
+    def producer_of(db, path, line_no)
+      full_path = File.expand_path(path)
+      instance = db.instances.values.flat_map(&:values).find do |inst|
+        File.expand_path(inst.path_ref.path) == full_path && inst.path_ref.line_no == line_no
       end
+      instance&.annotations&.[]("generated/script") || import_writing(db, full_path)
+    end
+
+    def import_writing(db, full_path)
+      db.instances_by_kind("Import").values.find do |import|
+        Archsight::Import.output_files(import).any? do |rel_path|
+          Archsight::Import.resources_path(Archsight.resources_dir, rel_path) == full_path
+        end
+      end&.name
+    end
+
+    def generated_by_note(producer)
+      producer.to_s.empty? ? "" : " (generated by #{producer})"
+    end
+
+    def configure_resources
+      Archsight.resources_dir = options[:resources] if options[:resources]
     end
 
     def load_database_for_analysis
@@ -374,12 +455,12 @@ module Archsight
     def filter_analyses(db)
       analyses = db.instances_by_kind("Analysis").values
       analyses = analyses.select { |a| Regexp.new(options[:filter], Regexp::IGNORECASE).match?(a.name) } if options[:filter]
-      analyses
+      analyses.sort_by(&:name) # same order as the dry run, independent of file layout
     end
 
     def print_analysis_dry_run(analyses)
       puts "Analyses to run#{" (filter: #{options[:filter]})" if options[:filter]}:"
-      analyses.sort_by(&:name).each_with_index do |analysis, idx|
+      analyses.each_with_index do |analysis, idx|
         timeout = analysis.annotations["analysis/timeout"] || "30s"
         desc = analysis.annotations["analysis/description"] || "(no description)"
         puts "  #{idx + 1}. #{analysis.name} [#{timeout}]"
@@ -392,6 +473,26 @@ module Archsight
       analyses.map { |analysis| executor.execute(analysis) }
     end
 
+    def write_analysis_typst(results)
+      typst = Archsight::Analysis::TypstRenderer.new(results, verbose: options[:verbose],
+                                                              template: typst_template_path).render
+      if options[:output]
+        File.write(options[:output], typst)
+        warn "Wrote #{options[:output]}"
+      else
+        puts typst
+      end
+    end
+
+    # Typst resolves imports relative to the importing file, so point from the output file to the template
+    def typst_template_path
+      return unless options[:template]
+
+      require "pathname"
+      base = Pathname.new(File.expand_path(File.dirname(options[:output] || ".")))
+      Pathname.new(File.expand_path(options[:template])).relative_path_from(base).to_s
+    end
+
     def print_analysis_results(results)
       require "tty-markdown"
 
@@ -419,14 +520,14 @@ module Archsight
     end
 
     def build_analysis_summary_markdown(results)
-      passed = results.count(&:success?)
+      completed = results.count(&:success?)
       failed = results.count(&:failed?)
-      with_findings = results.count(&:has_findings?)
+      with_warnings = results.count { |result| result.success? && result.warnings? }
 
       lines = ["---", "", "# Summary", ""]
-      lines << "- ✅ **#{passed}** passed"
+      lines << "- ✅ **#{completed}** completed"
       lines << "- ❌ **#{failed}** failed" if failed.positive?
-      lines << "- ⚠️ **#{with_findings}** with findings" if with_findings.positive?
+      lines << "- ⚠️ **#{with_warnings}** with warnings" if with_warnings.positive?
       lines.join("\n")
     end
 

data/lib/archsight/database.rb

@@ -75,6 +75,7 @@ module Archsight
         puts "parsing #{path}..." if @verbose
         File.extname(path) == ".md" ? load_page(path) : load_file(path)
       end
+      @instances.each_value { |instances| instances.each_value(&:apply_annotation_defaults!) }
 
       verify! if @verify
       derive_references! if @verify
@@ -93,6 +94,21 @@ module Archsight
       @instances[Archsight::Resources[kind]][instance]
     end
 
+    # The resource of a kind that has `identifier` as one of its aliases (a value of a unique annotation), when exactly
+    # one has; nil otherwise. A name always wins, so callers try instance_by_kind first.
+    def instance_by_alias(kind, identifier)
+      klass = Archsight::Resources[kind]
+      return nil unless klass
+
+      unique = klass.annotations.select(&:unique?).reject(&:pattern?)
+      return nil if unique.empty?
+
+      matches = instances_by_kind(kind).values.select do |instance|
+        unique.any? { |annotation| Array(annotation.value_for(instance)).map(&:to_s).include?(identifier) }
+      end
+      matches.first if matches.one?
+    end
+
     # Collect unique annotation values across all instances of a kind
     def annotation_values(kind, annotation)
       instances = instances_by_kind(kind).values
@@ -147,6 +163,8 @@ module Archsight
         obj["kind"] = current
       end
 
+      accept_old_annotations(obj)
+
       return unless obj["spec"].is_a?(Hash)
 
       obj["spec"].each do |verb, keys|
@@ -161,6 +179,28 @@ module Archsight
       end
     end
 
+    # A renamed annotation key (page/confluence is now link/confluence) is moved to its new key
+    def accept_old_annotations(obj)
+      annotations = obj.dig("metadata", "annotations")
+      return unless annotations.is_a?(Hash)
+
+      Archsight::Resources::ANNOTATION_ALIASES.each do |old_key, new_key|
+        next unless annotations.key?(old_key)
+
+        deprecate("annotation '#{old_key}' is renamed to '#{new_key}'#{legacy_frontmatter_hint(old_key)}")
+        value = annotations.delete(old_key)
+        annotations[new_key] ||= value
+      end
+    end
+
+    # In a page the annotation is a frontmatter key: `confluence:` is now `links: { confluence: ... }`
+    def legacy_frontmatter_hint(old_key)
+      return "" unless old_key.start_with?("page/")
+
+      name = old_key.delete_prefix("page/")
+      " (frontmatter `#{name}:` is now `links: { #{name}: <url> }`)"
+    end
+
     def deprecate(message)
       @deprecations << Deprecation.new(@current_ref, "#{message} (the old name will be removed in a future release)")
     end

data/lib/archsight/diagram/cli.rb

@@ -2,6 +2,7 @@
 
 require "optparse"
 require_relative "."
+require_relative "formatter"
 
 module Archsight
   module Diagram
@@ -18,7 +19,7 @@ module Archsight
       end
 
       # Runs with already-parsed options (:inputs, :output, :watch, :relation_filter,
-      # :style, :theme, :legend, :profile), e.g. from the `archsight diagram` Thor command.
+      # :style, :theme, :legend, :profile, :format, :check), e.g. from the `archsight diagram` Thor command.
       def run_with(options)
         if options[:inputs].empty?
           warn "archsight-diagram: missing input file\n\n#{usage}"
@@ -30,6 +31,8 @@ module Archsight
           return 1
         end
 
+        return format_files(options) if options[:format]
+
         if options[:watch]
           watch(options)
           0
@@ -76,6 +79,12 @@ module Archsight
           opts.on("-p", "--profile", "Print stage timing stats after each render") do
             options[:profile] = true
           end
+          opts.on("--format", "Re-indent the inputs in place instead of rendering them (-o: write a single input there)") do
+            options[:format] = true
+          end
+          opts.on("--check", "With --format: only list the inputs that are not formatted, exit 1 if any") do
+            options[:check] = true
+          end
           opts.on("-h", "--help", "Show this help") do
             puts opts
             exit 0
@@ -90,7 +99,46 @@ module Archsight
       end
 
       def usage
-        "Usage: archsight-diagram INPUT.asd [INPUT2.asd ...] [-o OUTPUT.svg] [--watch] [--relation=LIST] [--style=STYLE] [--theme=NAME] [--legend=MODE] [-p]"
+        "Usage: archsight-diagram INPUT.asd [INPUT2.asd ...] [-o OUTPUT.svg] [--watch] [--relation=LIST] [--style=STYLE] [--theme=NAME] [--legend=MODE] [-p] [--format [--check]]"
+      end
+
+      # `--format`: each input re-indented (see `Formatter`) and written back,
+      # or to `--output`; with `--check` nothing is written, the inputs that
+      # would change are listed and the status is 1 if there are any.
+      def format_files(options)
+        if options[:watch]
+          warn "archsight-diagram: --format cannot be combined with --watch"
+          return 1
+        end
+
+        statuses = options[:inputs].map { |input| format_once(input, options) }
+        statuses.all?(&:zero?) ? 0 : 1
+      end
+
+      def format_once(input, options)
+        source = File.read(input)
+        formatted = Formatter.format(source)
+        if options[:check]
+          return 0 if formatted == source
+
+          puts "archsight-diagram: #{input} is not formatted"
+          return 1
+        end
+
+        output = options[:output] || input
+        if output == input && formatted == source
+          puts "archsight-diagram: #{input} already formatted"
+        else
+          File.write(output, formatted)
+          puts "archsight-diagram: formatted #{output}"
+        end
+        0
+      rescue Archsight::Diagram::Error => e
+        warn "archsight-diagram: #{input}: #{e.message}"
+        1
+      rescue Errno::ENOENT => e
+        warn "archsight-diagram: #{e.message}"
+        1
       end
 
       def output_for(input, explicit_output)

data/lib/archsight/diagram/formatter.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "errors"
+require_relative "parser"
+
+module Archsight
+  module Diagram
+    # Tidies `.asd` source without rewriting it: every line is indented by
+    # its brace depth (`INDENT` per level, a line opening with `}` one level
+    # less), trailing whitespace is dropped, runs of blank lines become one
+    # and the file ends in exactly one newline. Comments, line breaks and
+    # one-line blocks (`component "a" { label "x"; tint "y" }`) stay as
+    # written. Works on the text, not the parse tree, because the lexer
+    # drops comments.
+    #
+    # A string spanning several lines keeps its blank lines; its
+    # continuation lines are indented one level below the line that opens
+    # it (the lexer strips that indentation, so it is not content).
+    #
+    # `format` checks that the result parses to the same diagram as the
+    # source (line numbers aside) and raises `Error` if not, so a bug here
+    # can never change a diagram.
+    module Formatter
+      INDENT = "  "
+
+      module_function
+
+      # @raise [Archsight::Diagram::Error] if `source` does not parse
+      def format(source)
+        before = comparable(Parser.parse(source))
+        formatted = reindent(source)
+        raise Error, "formatting would change the diagram" unless comparable(Parser.parse(formatted)) == before
+
+        formatted
+      end
+
+      def reindent(source)
+        lines = []
+        depth = 0
+        in_string = false
+        source.each_line(chomp: true) do |raw|
+          text = raw.rstrip
+          continuation = in_string
+          closers, delta, in_string = scan(text, in_string)
+          text = text.lstrip unless continuation && text.empty?
+          level = continuation ? depth + 1 : [depth - closers, 0].max
+          lines << (text.empty? ? "" : (INDENT * level) + text) << continuation
+          depth = [depth + delta, 0].max
+        end
+        tidy(lines.each_slice(2).to_a)
+      end
+
+      # `[leading closing braces, brace depth change, still inside a string
+      # at the end]` of one line, ignoring braces in strings and comments.
+      def scan(text, in_string)
+        scanner = StringScanner.new(text)
+        delta = 0
+        closers = 0
+        leading = !in_string
+        until scanner.eos?
+          if in_string
+            in_string = false if scanner.scan(/(?:[^"\\]|\\.)*"/)
+            scanner.terminate if in_string
+            leading = false
+          elsif scanner.skip(/\s+/)
+            next
+          elsif scanner.skip(/#.*/)
+            break
+          elsif scanner.skip(/"/)
+            in_string = true
+            leading = false
+          elsif scanner.skip(/\{/)
+            delta += 1
+            leading = false
+          elsif scanner.skip(/\}/)
+            delta -= 1
+            closers += 1 if leading
+          else
+            scanner.skip(/[^\s"{}#]+/)
+            leading = false
+          end
+        end
+        [closers, delta, in_string]
+      end
+
+      # Joins `[line, inside a string]` pairs: one blank line at most between
+      # statements (blank lines inside a string are content), none at the
+      # start or end.
+      def tidy(pairs)
+        out = []
+        pairs.each do |line, continuation|
+          next if line.empty? && !continuation && (out.empty? || out.last.empty?)
+
+          out << line
+        end
+        out.pop while out.last&.empty?
+        out.empty? ? "" : "#{out.join("\n")}\n"
+      end
+
+      # The parse tree without line numbers, which formatting may change.
+      def comparable(node)
+        case node
+        when Array then node.map { |child| comparable(child) }
+        when Hash then node.transform_values { |value| comparable(value) }
+        when Struct then [node.class, node.to_h.except(:line).transform_values { |value| comparable(value) }]
+        else node
+        end
+      end
+    end
+  end
+end

data/lib/archsight/diagram/routing/edge_router/orthogonal_path.rb

@@ -24,6 +24,14 @@ module Archsight
         # resorting to a two-turn mid-jog.
         SINGLE_TURN_RATIOS = [0.5, 0.1, 0.9].freeze
 
+        # How far a single turn's exit may also move off `a`'s center, away
+        # from `b`, as a fraction of `a`'s extent: a source whose center
+        # lies just past `b`'s side would otherwise turn right along that
+        # side, in a stub too short to read (see `EdgeRouter::MIN_END_LEG`).
+        # Only offered for such a source: anywhere else the centered exit
+        # stays the only one.
+        EXIT_SHIFT = 0.25
+
         # A single turn entering the target off its center, remembering by
         # how far. Entering nearer the source is always exactly that much
         # shorter, so `EdgeRouter.score_candidates` charges it back: the
@@ -57,8 +65,10 @@ module Archsight
           dx = b.x - a.x
           dy = b.y - a.y
 
-          horizontal = SINGLE_TURN_RATIOS.map { |ratio| single_turn_horizontal_first(a, b, dx, dy, ratio) }
-          vertical = SINGLE_TURN_RATIOS.map { |ratio| single_turn_vertical_first(a, b, dx, dy, ratio) }
+          # Centered exits first, the ones shifted away from `b` after them.
+          exits = [0.0, EXIT_SHIFT]
+          horizontal = exits.product(SINGLE_TURN_RATIOS).map { |shift, ratio| single_turn_horizontal_first(a, b, dx, dy, ratio, shift) }
+          vertical = exits.product(SINGLE_TURN_RATIOS).map { |shift, ratio| single_turn_vertical_first(a, b, dx, dy, ratio, shift) }
           # Centered entries first (dominant axis leading), off-center ones after.
           singles = if dx.abs >= dy.abs
                       [horizontal.first, vertical.first, *horizontal.drop(1), *vertical.drop(1)]
@@ -125,15 +135,21 @@ module Archsight
         # also guarantees the corner-to-entry run (at x = entry_x) clears `a`
         # entirely; and (2) `a`'s own y sits outside `b`'s vertical span, so
         # the exit-to-corner run (at y = a.y) clears `b` entirely.
-        def single_turn_horizontal_first(a, b, dx, dy, ratio = 0.5)
+        # `exit_shift` moves the exit that fraction of `a`'s height away from
+        # `b` (see `EXIT_SHIFT`).
+        def single_turn_horizontal_first(a, b, dx, dy, ratio = 0.5, exit_shift = 0.0)
           return nil if dx.zero?
 
           corner_x = ratio == 0.5 ? b.x : b.left + (b.width * ratio)
           return nil if dx.positive? ? (corner_x <= a.right) : (corner_x >= a.left)
-          return nil unless a.y < b.top || a.y > b.bottom
 
-          exit_point = [dx.positive? ? a.right : a.left, a.y]
-          corner = [corner_x, a.y]
+          return nil unless exit_shift.zero? || short_run?(a.y, b.top, b.bottom)
+
+          exit_y = a.y - ((dy <=> 0) * a.height * exit_shift)
+          return nil unless exit_y < b.top || exit_y > b.bottom
+
+          exit_point = [dx.positive? ? a.right : a.left, exit_y]
+          corner = [corner_x, exit_y]
           entry_point = [corner_x, dy.positive? ? b.top : b.bottom]
           off_center(ratio, corner_x - b.x, [exit_point, corner, entry_point])
         end
@@ -141,19 +157,31 @@ module Archsight
         # The transpose of `single_turn_horizontal_first`: exit `a` from
         # whichever top/bottom edge faces `b`, corner at `(a.x, b.y)`, then
         # straight into `b`'s facing left/right edge.
-        def single_turn_vertical_first(a, b, dx, dy, ratio = 0.5)
+        def single_turn_vertical_first(a, b, dx, dy, ratio = 0.5, exit_shift = 0.0)
           return nil if dy.zero?
 
           corner_y = ratio == 0.5 ? b.y : b.top + (b.height * ratio)
           return nil if dy.positive? ? (corner_y <= a.bottom) : (corner_y >= a.top)
-          return nil unless a.x < b.left || a.x > b.right
 
-          exit_point = [a.x, dy.positive? ? a.bottom : a.top]
-          corner = [a.x, corner_y]
+          return nil unless exit_shift.zero? || short_run?(a.x, b.left, b.right)
+
+          exit_x = a.x - ((dx <=> 0) * a.width * exit_shift)
+          return nil unless exit_x < b.left || exit_x > b.right
+
+          exit_point = [exit_x, dy.positive? ? a.bottom : a.top]
+          corner = [exit_x, corner_y]
           entry_point = [dx.positive? ? b.left : b.right, corner_y]
           off_center(ratio, corner_y - b.y, [exit_point, corner, entry_point])
         end
 
+        # Whether a centered exit at `coord` lies just outside `b`'s span
+        # `low..high`, so its run into `b` would be shorter than
+        # `EdgeRouter::MIN_END_LEG`.
+        def short_run?(coord, low, high)
+          gap = coord < low ? low - coord : coord - high
+          gap.positive? && gap < EdgeRouter::MIN_END_LEG
+        end
+
         def off_center(ratio, offset, points)
           ratio == SINGLE_TURN_RATIOS.first ? points : OffCenterPath.new(points, offset.abs)
         end