tessella 0.3.0

data/lib/tessella/lint/shadows.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # Drop shadows: ░ (U+2591) one column right of a frame on every
+        # row but the first, and a bottom bar one row down, from one
+        # column in to the shadow column. The slips are a shadow on the
+        # closing row only and a bar one cell short; both look fine a
+        # line at a time. Only a frame that already carries a shadow is
+        # inspected: ░ as fill never sits against a box-drawing edge.
+        module Shadows
+            SHADOW = "░"
+            TOP_LEFT = "┌┏╔╭┎┍"
+            BOT_LEFT = "└┗╚╰┖┕"
+            SHADOW_TAIL = /#{SHADOW}+\z/
+            SHADOW_BAR = /\A *#{SHADOW}+\z/
+
+            private
+
+            def check_shadows(sec)
+                row = 0
+                row = shadow_at(sec, row) while row < sec.lines.length
+            end
+
+            # The row to resume from: past a shadowed frame opened at
+            # row, once checked, or the next row.
+            def shadow_at(sec, row)
+                span = frame_span(sec.lines, row)
+                return row + 1 unless span&.any? { shadow_tail?(sec.lines[it]) }
+
+                check_shadow_geometry(sec, span)
+                span.last + 1
+            end
+
+            # Rows top..bottom of the frame opened at top, or nil: the
+            # run ends at the first row whose left edge is a bottom-left
+            # corner in the same display column.
+            def frame_span(lines, top)
+                left = left_edge(lines[top])
+                return nil unless left && TOP_LEFT.include?(left[0])
+
+                ((top + 1)...lines.length).each do |i|
+                    edge = left_edge(lines[i])
+                    return nil unless edge && edge[1] == left[1]
+                    return top..i if BOT_LEFT.include?(edge[0])
+                end
+                nil
+            end
+
+            # [first non-blank char, its display column], or nil.
+            def left_edge(line)
+                indent = line[/\A */]
+                return nil if indent.length == line.length
+
+                [line[indent.length], @overhead + indent.length + 1]
+            end
+
+            # A shadow cell hanging off a box-drawing edge; a run wider
+            # than one cell is a column error, left to the geometry.
+            def shadow_tail?(line)
+                rest = unshadowed(line)
+                rest.length < line.length && rest[-1].to_s.match?(BOX_CHAR)
+            end
+
+            def unshadowed(line) = line.sub(SHADOW_TAIL, "")
+
+            def check_shadow_geometry(sec, span)
+                top = sec.lines[span.first]
+                if shadow_tail?(top)
+                    report(sec, span.first, "drop shadow on the frame's " \
+                                            "top row (offset it one row " \
+                                            "down)")
+                end
+                # Off the frame edge, so a stray top-row shadow does not
+                # drag the reference column with it.
+                col = end_column(unshadowed(top)) + 1
+                span.drop(1).each { check_shadow_row(sec, it, col) }
+                check_shadow_bar(sec, span, col)
+            end
+
+            def check_shadow_row(sec, i, col)
+                line = sec.lines[i]
+                unless shadow_tail?(line)
+                    return report(sec, i, "row has no drop shadow at " \
+                                          "column #{col}")
+                end
+                actual = end_column(line)
+                return if actual == col
+
+                report(sec, i, "drop shadow at column #{actual}, frame's " \
+                               "is at #{col}")
+            end
+
+            # The bar runs from one column right of the frame's left
+            # edge to the shadow column, so the L closes on both ends.
+            def check_shadow_bar(sec, span, col)
+                bar = sec.lines[span.last + 1]
+                unless bar&.match?(SHADOW_BAR)
+                    return report(sec, span.last,
+                                  "drop shadow has no bottom bar")
+                end
+                left = left_edge(sec.lines[span.first])[1]
+                check_bar_ends(sec, span.last + 1, bar, [left + 1, col])
+            end
+
+            def check_bar_ends(sec, i, bar, ends)
+                start = left_edge(bar)[1]
+                stop = end_column(bar)
+                if start != ends[0]
+                    report(sec, i, "bottom bar starts at column #{start}, " \
+                                   "should start at #{ends[0]}")
+                end
+                return if stop == ends[1]
+
+                report(sec, i, "bottom bar ends at column #{stop}, " \
+                               "should reach the shadow column #{ends[1]}")
+            end
+        end
+    end
+end

data/lib/tessella/lint/target_rows.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # The checks a target adds to a line (DESIGN.md, "Width
+        # targets"): under :web, emoji-capable glyphs, and wide glyphs
+        # or braille on an aligned row, which a browser does not keep a
+        # column wide; under :cjk, ambiguous glyphs on an aligned row,
+        # two columns there. Kept apart so Lines stays under budget.
+        module TargetRows
+            private
+
+            def check_target_row(sec, i, line)
+                check_web_row(sec, i, line) if @opts[:web]
+                check_cjk_row(sec, i, line) if @opts[:target] == :cjk
+            end
+
+            def check_web_char(sec, i, ch)
+                return unless Lint.emoji_risk?(ch.ord)
+
+                report(sec, i, "#{glyph("emoji-capable", ch)} (web target)")
+            end
+
+            def check_web_row(sec, i, line)
+                return unless line.match?(STRUCTURAL)
+
+                line.each_char do |ch|
+                    next unless Lint.wide?(ch.ord)
+
+                    report(sec, i, "#{glyph("wide", ch)} on aligned row " \
+                                   "(web target)")
+                end
+                check_web_braille(sec, i, line)
+            end
+
+            # Braille comes from a fallback font in a browser, wider
+            # than a column: named once a row, as a chart has many.
+            def check_web_braille(sec, i, line)
+                ch = line[BRAILLE] or return
+
+                report(sec, i, "#{glyph("braille", ch)} on aligned row " \
+                               "(web target: not a column wide)")
+            end
+
+            # Under :cjk an ambiguous glyph that is not box drawing (·, é,
+            # ●) on a row that must line up takes two columns: named,
+            # as the drift and geometry checks measure it so.
+            def check_cjk_row(sec, i, line)
+                return unless line.match?(STRUCTURAL)
+
+                line.each_char.grep_v(BOX_CHAR).uniq.each do |ch|
+                    next unless Width.class_of(ch) == :A
+
+                    report(sec, i, "#{glyph("ambiguous", ch)} on aligned row " \
+                                   "(cjk target: 2 columns#{stand_in(ch)})")
+                end
+            end
+
+            # The small head that lines up in place of a full-size one.
+            def stand_in(ch)
+                small = { "▲" => "▴", "▼" => "▾" }[ch]
+                small ? "; #{small} lines up" : ""
+            end
+        end
+    end
+end

data/lib/tessella/lint.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A lint for text figures (DESIGN.md, "Lint"), ported from the
+    # ascii-art skill's scripts/artlint.rb: tabs, invisible glyphs,
+    # trailing blanks, a column budget, forbidden comment-breaking
+    # sequences, drop-shadow geometry, ASCII structure mixed with
+    # Unicode box drawing, a vertical anchor one column off -- and, on
+    # request, box sides and connectors (geometry: true) and one
+    # Markdown fence at a time (fences: true). Tessella.lint and
+    # Tessella.alphabet, at the bottom of this file, are the entries.
+    module Lint
+        # One finding: the line of the text it is on, 1-based, and what
+        # is wrong there.
+        Finding = Data.define(:line, :message)
+
+        # One --ruler row: a line's rendered width (the prefix and
+        # suffix included) and the display columns of its verticals.
+        Ruler = Data.define(:line, :width, :verticals)
+
+        # What Tessella.lint returns: every finding, in the order
+        # artlint.rb reported them, and a Ruler per line linted.
+        Report = Data.define(:findings, :rulers) do
+            def clean? = findings.empty?
+        end
+
+        # A run of lines linted as one text: the whole input, or one
+        # fenced block's body. first is the input line of lines[0];
+        # exempt says an allow-mixed marker came just before the fence.
+        Section = Data.define(:lines, :first, :exempt)
+
+        VERTICALS = "│┃║╎╏┆┇┊┋|"
+        BRAILLE = /[\u2801-\u28FF]/
+        STRUCTURAL = /[─-╿|]/
+        BOX_CHAR = /[─-╿]/
+
+        # Box structure in ASCII: a line with one of these pairs, or a
+        # | at its first or last non-blank column. The bare "--" is
+        # guarded by word boundaries, so "--align" in a label and
+        # "well--known" in a caption are words, not a rule.
+        ASCII_STRUCT_PAIR =
+            /\+-|-\+|(?<!\w)--(?!\w)|\|-|-\||\+\||\|\+|->|<-/
+        INLINE_CODE = /`[^`\n]*`/
+
+        # Exempts the one figure that follows it from the mixing check,
+        # whatever comment syntax wraps it: <!-- artlint: allow-mixed -->,
+        # # tessella: allow-mixed, ...
+        MIXED_MARKER = /(?:artlint|tessella):\s*allow-mixed/
+
+        # Comment-breaking sequences per host syntax, for forbid:.
+        # :trailing_backslash is a positional check, not a substring.
+        FORBID_PRESETS = {
+            "xml" => ["--"], "html" => ["--"],
+            "c-block" => ["*/", "/*"], "rust" => ["*/", "/*"],
+            "c-line" => [:trailing_backslash],
+            "haskell" => ["{-", "-}"], "ocaml" => ["(*", "*)"],
+            "pascal" => ["}", "(*", "*)"], "d" => ["/+", "+/"],
+            "lisp" => ["#|", "|#"], "lua" => ["]]"],
+            "python-doc" => ['"""'], "cdata" => ["]]>"],
+            "markdown-fence" => ["```", "~~~"]
+        }.freeze
+
+        DEFAULTS = { width: 78, prefix: "", suffix: "", web: false,
+                     target: nil,
+                     forbid: [],
+                     no_wide: false, ascii: false, allow_mixed: false,
+                     fences: false, geometry: false, borders: [] }.freeze
+
+        def self.wide?(code) = Width.char(code) == 2
+        def self.invisible?(code) = Width.char(code).zero?
+
+        # A space separator (Zs) other than U+0020: U+00A0, U+202F,
+        # U+3000, ... Drawn as a blank, so no display tells it from a
+        # space, yet a figure holding one is always an accident.
+        def self.look_alike_space?(ch) = ch != " " && ch.match?(/\p{Zs}/)
+
+        def self.emoji_risk?(code) = Target.emoji_risk?(code)
+
+        def self.width_of(text) = text.each_char.sum { Width.char(it.ord) }
+
+        # Linted for opts[:target] (web: true is :web), else the
+        # current one (Target): widths are that target's.
+        def self.run(source, opts)
+            resolved = Options.resolve(DEFAULTS.merge(opts))
+            Target.with(resolved[:target]) do
+                Runner.new(resolved).run(text(source))
+            end
+        end
+
+        # The source as UTF-8, invalid bytes kept for the lint to name:
+        # a String of bytes, or an IO read to its end.
+        def self.text(source)
+            raw = source.respond_to?(:read) ? source.read : source
+            unless raw.is_a?(String)
+                raise ArgumentError, "source must be a String or IO: " \
+                                     "#{source.inspect}"
+            end
+
+            raw.dup.force_encoding(Encoding::UTF_8)
+        end
+    end
+
+    # Validates Tessella.lint's options: width a positive Integer,
+    # prefix and suffix Strings, and forbid a list of preset names or literal
+    # sequences, resolved here to the sequences.
+    module Lint
+        module Options
+            def self.resolve(opts)
+                Check.positive_integer!(opts[:width], "width")
+                %i[prefix suffix].each { string!(opts, it) }
+                target = target(opts)
+                opts.merge(forbid: forbid(opts[:forbid]),
+                           borders: borders(opts[:borders]),
+                           target: target, web: target == :web)
+            end
+
+            def self.string!(opts, key)
+                return if opts[key].is_a?(String)
+
+                raise ArgumentError, "#{key} must be a String: " \
+                                     "#{opts[key].inspect}"
+            end
+
+            def self.target(opts)
+                return Target.check!(opts[:target]) if opts[:target]
+
+                opts[:web] ? :web : Target.current
+            end
+
+            # Each a Borders name, Set or glyph String, as its Set.
+            def self.borders(list)
+                Array(list).map do |style|
+                    next Borders.custom(style).first if Borders.custom?(style)
+
+                    Borders.fetch(style)
+                end
+            end
+
+            def self.forbid(list)
+                Array(list).flat_map do |seq|
+                    seq = seq.to_s
+                    raise ArgumentError, "forbid: empty sequence" if
+                        seq.empty?
+
+                    FORBID_PRESETS.fetch(seq) { [seq] }
+                end
+            end
+        end
+    end
+
+    # width: 78, prefix: "", suffix: "", web: false, forbid: [],
+    # no_wide: false, ascii: false, allow_mixed: false, fences: false,
+    # geometry: false, borders: [] (Lint::DEFAULTS); returns a Lint::Report.
+    def self.lint(source, **opts) = Lint.run(source, opts)
+
+    # "ascii", or "utf-8" and the glyph classes the source holds.
+    def self.alphabet(source) = Lint::Alphabet.of(Lint.text(source))
+end

data/lib/tessella/meter.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A one-line meter (DESIGN.md, "Meters and rules"): a progress bar
+    # or gauge, as the ascii-art skill's ui.md draws one --
+    # "[██████······] 50 %". The fill/track pair is a style from
+    # Glyphs::METERS or glyphs of one's own, of one width class; the
+    # block style fills its last cell by eighths. title: goes before
+    # the bar, the percentage after it unless label: false;
+    # title_width: pads the title to that many columns, so meters with
+    # titles of different lengths line up. orientation: :vertical
+    # stands the bar up (MeterUpright).
+    module Meter
+        EIGHTHS = " ▏▎▍▌▋▊▉".chars.freeze
+
+        DEFAULTS = { style: :block, title: nil, label: true,
+                     brackets: true, ascii: false, title_width: nil }.freeze
+
+        # orientation: :horizontal takes width: (20), :vertical height:
+        # (8); the other is refused.
+        def self.build(fraction, orientation: :horizontal, **opts)
+            share = fraction!(fraction)
+            opts = sized!(orientation,
+                          DEFAULTS.merge(ascii: Target.ascii?, **opts))
+            return MeterUpright.build(share, opts) if orientation == :vertical
+
+            Block.new([line(share, opts)])
+        end
+
+        def self.sized!(orientation, opts)
+            sizes = { horizontal: [:width, 20], vertical: [:height, 8] }
+            own, default = sizes.fetch(orientation) do
+                raise ArgumentError, "orientation must be :horizontal or " \
+                                     ":vertical: #{orientation.inspect}"
+            end
+            other = (%i[width height] - [own]).first
+            raise ArgumentError, "a #{orientation} meter takes no #{other}:" if
+                opts.key?(other)
+
+            opts.merge(own => opts.fetch(own, default))
+        end
+
+        def self.line(share, opts)
+            Check.positive_integer!(opts[:width], "width")
+            bar = bar(share, opts[:width], glyphs(opts), eighths?(opts))
+            [title_of(opts), opts[:brackets] ? "[#{bar}]" : bar,
+             (percent(share) if opts[:label])].compact.join(" ")
+        end
+
+        # [fill, track]: the style's, or classic's under ascii:.
+        def self.glyphs(opts)
+            pair!(opts[:ascii] ? :classic : opts[:style], opts[:ascii])
+        end
+
+        def self.title_of(opts)
+            opts[:title] && title!(opts[:title], opts[:title_width],
+                                   opts[:ascii])
+        end
+
+        def self.eighths?(opts)
+            Borders.name(opts[:style]) == :block && !opts[:ascii]
+        end
+
+        # The title, padded to title_width: columns when given.
+        def self.title!(title, title_width, ascii)
+            text = Compose.text!("title", title, ascii)
+            return text unless title_width
+
+            Check.positive_integer!(title_width, "title_width")
+            if Width.of(text) > title_width
+                raise ArgumentError, "title #{text.inspect} is wider than " \
+                                     "title_width #{title_width}"
+            end
+            Width.ljust(text, title_width)
+        end
+
+        # A number 0..1, or a String "45%" / "0.45".
+        def self.fraction!(value)
+            number = value.is_a?(String) ? parse(value) : value
+            return number.to_f if number.is_a?(Numeric) &&
+                                  number.to_f.between?(0.0, 1.0)
+
+            raise ArgumentError, "fraction must be 0..1 or 0%..100%: " \
+                                 "#{value.inspect}"
+        end
+
+        def self.parse(text)
+            return Float(text.delete_suffix("%"), exception: false)&./(100) if
+                text.end_with?("%")
+
+            Float(text, exception: false)
+        end
+
+        # [fill, track] from a style name or two glyphs of one's own.
+        def self.pair!(style, ascii)
+            key = Borders.name(style)
+            glyphs = Glyphs::METERS.fetch(key) { style.to_s }.chars
+            unless glyphs.size == 2
+                raise ArgumentError, "unknown meter style: #{style.inspect} " \
+                                     "(#{Glyphs::METERS.keys.join(", ")}, " \
+                                     "or a fill and a track glyph)"
+            end
+            same_class!(glyphs, style)
+            glyphs.each { Compose.text!("meter glyph", it, ascii) }
+        end
+
+        def self.same_class!(glyphs, style)
+            classes = Width.classes(glyphs.join)
+            return if classes.size <= 1
+
+            raise ArgumentError, "meter style #{style.inspect} mixes width " \
+                                 "classes: #{classes.join(", ")}"
+        end
+
+        # width glyphs, filled then tracked: counted in glyphs, not
+        # columns, so a two-column pair (or a cjk target's) keeps its
+        # length as it fills.
+        def self.bar(share, width, glyphs, eighths)
+            fill, track = glyphs
+            units = (share * width * (eighths ? 8 : 1)).round
+            full, rem = eighths ? units.divmod(8) : [units, 0]
+            cells = (fill * full) + (rem.zero? ? "" : EIGHTHS[rem])
+            cells + (track * (width - cells.length))
+        end
+
+        def self.percent(share) = "#{(share * 100).round} %"
+    end
+
+    # fraction (0..1, or "45%"), style: :block, width: 20, title: nil,
+    # label: true, brackets: true, ascii: false, title_width: nil,
+    # orientation: :horizontal (:vertical takes height: 8 instead).
+    def self.meter(fraction, **) = Meter.build(fraction, **)
+end

data/lib/tessella/meter_upright.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A meter standing up (orientation: :vertical): the bar a column of
+    # height: cells (8 by default), filled from the bottom -- the block
+    # style tops its fill by eighths, ▁ to ▇ -- between a ─ above and
+    # below (- in ASCII; none with brackets: false), the title over it
+    # and the percentage under it, each line centred on the bar. Meters
+    # side by side are `compose beside`'s.
+    module MeterUpright
+        RISE = " ▁▂▃▄▅▆▇".chars.freeze
+
+        def self.build(share, opts)
+            Check.positive_integer!(opts[:height], "height")
+            column = column(share, opts[:height], Meter.glyphs(opts),
+                            Meter.eighths?(opts))
+            Block.new(centre(lines(share, column, opts)))
+        end
+
+        # The bar's cells, top to bottom.
+        def self.column(share, height, glyphs, eighths)
+            fill, track = glyphs
+            units = (share * height * (eighths ? 8 : 1)).round
+            full, rem = eighths ? units.divmod(8) : [units, 0]
+            cells = Array.new(full, fill)
+            cells << RISE[rem] unless rem.zero?
+            (Array.new(height - cells.size, track) + cells.reverse)
+        end
+
+        def self.lines(share, column, opts)
+            cap = opts[:ascii] ? "-" : "─"
+            bar = opts[:brackets] ? [cap, *column, cap] : column
+            [Meter.title_of(opts), *bar,
+             (Meter.percent(share) if opts[:label])].compact
+        end
+
+        # Every line centred on the widest; trailing blanks dropped.
+        def self.centre(lines)
+            widest = lines.map { Width.of(it) }.max
+            lines.map { Width.center(it, widest).rstrip }
+        end
+    end
+end