tessella 0.3.0

data/lib/tessella/lint/geometry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # Box geometry (geometry: true), ported from the skills shelf's
+        # tests/lib/check-readme.py: a box opened by a top-left corner
+        # keeps its sides at the same two columns down to its bottom
+        # edge -- a side wandering by one column is the commonest
+        # hand-drawn defect -- and a connector (a vertical or an arrow
+        # head) hangs from something above it: a junction, a vertical,
+        # an arrow, a label, never a plain edge or blank.
+        #
+        # check-readme.py knew the light set only. Here every
+        # box-drawing glyph is read by its arms (which of up, down,
+        # left, right it reaches), so light, heavy, double, rounded,
+        # dashed and mixed junctions (╤ ╫ ...) are all one case, and a
+        # custom border set (borders:) gives its six glyphs the arms
+        # of their role. ASCII boxes (+ - |) keep their own rules.
+        # Columns are display columns, so a wide glyph is two; a
+        # vertical under a horizontal that has the same vertical above
+        # it is a crossing (a lifeline under an arrow), not a hanger.
+        module Geometry
+            include Boxes
+            include Connectors
+
+            UP = 1
+            DOWN = 2
+            LEFT = 4
+            RIGHT = 8
+
+            # The arms of U+2500..U+257F, one hex digit each (UP 1,
+            # DOWN 2, LEFT 4, RIGHT 8), generated from the Unicode 15.1
+            # character names: HORIZONTAL is left and right, VERTICAL
+            # up and down, the diagonals none.
+            ARMS = "cc33cc33cc33aaaa666699995555bbbbbbbb77777777eeeeeeee" \
+                   "ddddddddffffffffffffffffcc33c3aaa666999555bbb777eeed" \
+                   "ddfffa65900041824182c3c3"
+                   .each_char.with_index.to_h do |digit, i|
+                       [(0x2500 + i).chr(Encoding::UTF_8), digit.to_i(16)]
+                   end.freeze
+
+            # Arms by role in a custom border set.
+            ROLE_ARMS = {
+                tl: DOWN | RIGHT, tr: DOWN | LEFT, bl: UP | RIGHT,
+                br: UP | LEFT, h: LEFT | RIGHT, v: UP | DOWN
+            }.freeze
+
+            SIDE_A = "|+"
+            ABOVE_VERT_A = "|+-"
+            ABOVE_ARROW_A = "|+-v▼▾"
+            ARROWS = "▼▾"
+            # The second column of a wide glyph: structural to nothing.
+            TAIL = "\u0000"
+
+            # A row as one glyph per display column.
+            def self.cells(line)
+                line.each_char.with_object([]) do |ch, out|
+                    case Width.char(ch.ord)
+                    when 0 then next
+                    when 2 then out.push(ch, TAIL)
+                    else out << ch
+                    end
+                end
+            end
+
+            def self.at(row, col) = (col.negative? ? nil : row[col]) || " "
+
+            # Each declared border set's glyphs by the roles they play
+            # (ASCII + - | stay with the ASCII rules): a glyph used for
+            # several roles, as * for all four corners, plays them all.
+            def self.roles_for(sets)
+                roles = Hash.new { |h, k| h[k] = [] }
+                sets.each do |set|
+                    ROLE_ARMS.each_key do |role|
+                        glyph = set.public_send(role)
+                        roles[glyph] |= [role] unless "+-|".include?(glyph)
+                    end
+                end
+                roles
+            end
+
+            # The arms table for one run: the box-drawing glyphs, and
+            # each custom glyph with the union of its roles' arms.
+            def self.arms_for(roles)
+                roles.each_with_object(ARMS.dup) do |(glyph, list), arms|
+                    arms[glyph] = list.sum { ROLE_ARMS[it] } |
+                                  arms.fetch(glyph, 0)
+                end
+            end
+
+            private
+
+            def check_geometry(sec)
+                @roles ||= Geometry.roles_for(@opts[:borders])
+                @arms ||= Geometry.arms_for(@roles)
+                rows = sec.lines.map { Geometry.cells(it) }
+                rows.each_index { check_boxes(sec, rows, it) }
+                (1...rows.length).each { check_connectors(sec, rows, it) }
+            end
+
+            def arms(ch) = @arms.fetch(ch, 0)
+
+            def role?(ch, role) = @roles.fetch(ch, []).include?(role)
+
+            # A corner: the box-drawing glyph with exactly its arms, or
+            # a custom glyph declared for it.
+            def corner?(ch, role)
+                arms?(ch, ROLE_ARMS[role], exact: true) || role?(ch, role)
+            end
+
+            # Every arm in bits, and none outside them when exact.
+            def arms?(ch, bits, exact: false)
+                a = arms(ch)
+                a.allbits?(bits) && (!exact || a == bits)
+            end
+
+            def geo_col(col) = @overhead + col + 1
+        end
+    end
+end

data/lib/tessella/lint/geometry_checks.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # Geometry's two checks, on rows already split into display
+        # columns (Geometry.cells) and glyphs read by their arms
+        # (Geometry#arms): boxes keep their sides, connectors hang from
+        # something.
+        module Geometry
+            # A box opened on row i: scanned left to right, each opening
+            # corner followed down to its bottom edge. :uni is any
+            # box-drawing set, :asc a +-| box.
+            module Boxes
+                private
+
+                def check_boxes(sec, rows, i)
+                    j = 0
+                    j = box_at(sec, rows, [i, j]) while j < rows[i].length
+                end
+
+                # The column to resume the scan from.
+                def box_at(sec, rows, pos)
+                    kind = box_kind(rows, *pos) or return pos[1] + 1
+                    k = box_end(rows[pos[0]], pos[1], kind)
+                    return pos[1] + 1 unless
+                        top_right?(Geometry.at(rows[pos[0]], k), kind)
+
+                    follow_box(sec, rows, [*pos, k], kind) if
+                        side_below?(rows, pos, kind)
+                    k + 1
+                end
+
+                # :uni for a box-drawing top-left corner, :asc for a +
+                # opening a -- run that is not the bottom edge of the box
+                # above; nil otherwise.
+                def box_kind(rows, i, j)
+                    return :uni if corner?(rows[i][j], :tl)
+
+                    :asc if ascii_corner?(rows[i], j) &&
+                            !(i.positive? &&
+                              SIDE_A.include?(Geometry.at(rows[i - 1], j)))
+                end
+
+                def ascii_corner?(row, j)
+                    row[j] == "+" && Geometry.at(row, j + 1) == "-" &&
+                        !(j.positive? && "-+".include?(Geometry.at(row, j - 1)))
+                end
+
+                # The column after the top edge's run of horizontals.
+                def box_end(row, j, kind)
+                    k = j + 1
+                    k += 1 while k < row.length && top_run?(row, k, kind)
+                    k
+                end
+
+                def top_run?(row, k, kind)
+                    if kind == :uni
+                        return arms?(row[k], LEFT | RIGHT) &&
+                               !role?(row[k], :tr)
+                    end
+
+                    row[k] == "-" ||
+                        (row[k] == "+" && Geometry.at(row, k + 1) == "-")
+                end
+
+                def top_right?(ch, kind)
+                    return ch == "+" if kind == :asc
+
+                    corner?(ch, :tr)
+                end
+
+                # A box's side: a vertical, or a junction on one.
+                def side?(ch, kind)
+                    return SIDE_A.include?(ch) if kind == :asc
+
+                    vertical = UP | DOWN
+                    arms?(ch, vertical) ||
+                        (arms?(ch, LEFT | RIGHT) && arms(ch).anybits?(vertical))
+                end
+
+                def side_below?(rows, pos, kind)
+                    below = rows[pos[0] + 1] or return false
+                    side?(Geometry.at(below, pos[1]), kind)
+                end
+
+                # Down from the opening row to the first row that settles
+                # the box: its bottom edge, or a side off its column.
+                def follow_box(sec, rows, box, kind)
+                    last = ((box[0] + 1)...rows.length).find do |i2|
+                        box_settled?(sec, rows[i2], [*box, i2], kind)
+                    end
+                    return if last
+
+                    report(sec, box[0], "box opened at col " \
+                                        "#{geo_col(box[1])} has no bottom " \
+                                        "edge")
+                end
+
+                def box_settled?(sec, row, pos, kind)
+                    if bottom_left?(row, pos[1], kind)
+                        check_bottom(sec, row, pos, kind)
+                        return true
+                    end
+                    bad = off_side(row, pos, kind) or return false
+
+                    report(sec, pos[3], "side of #{opened(sec, pos)} is off " \
+                                        "at col #{geo_col(bad)}")
+                    true
+                end
+
+                # The column of a side not where the box opened it, or
+                # nil when both sides are in place.
+                def off_side(row, pos, kind)
+                    _, j, k, = pos
+                    return j unless side?(Geometry.at(row, j), kind)
+
+                    k unless side?(Geometry.at(row, k), kind)
+                end
+
+                def bottom_left?(row, j, kind)
+                    left = Geometry.at(row, j)
+                    return corner?(left, :bl) if kind == :uni
+
+                    left == "+" && Geometry.at(row, j + 1) == "-"
+                end
+
+                def check_bottom(sec, row, pos, kind)
+                    right = Geometry.at(row, pos[2])
+                    return if closes?(right, kind)
+
+                    report(sec, pos[3], "#{opened(sec, pos)} does not close " \
+                                        "at col #{geo_col(pos[2])} (found " \
+                                        "'#{right}')")
+                end
+
+                # A bottom-right corner, or a junction rising from it.
+                def closes?(ch, kind)
+                    return ch == "+" if kind == :asc
+
+                    (arms?(ch, UP | LEFT) && !arms(ch).anybits?(DOWN)) ||
+                        role?(ch, :br)
+                end
+
+                def opened(sec, pos)
+                    "box opened at line #{sec.first + pos[0]} col " \
+                        "#{geo_col(pos[1])}"
+                end
+            end
+
+            # A vertical or an arrow head hangs from something above:
+            # a glyph reaching down, or (ASCII) a | + or - edge.
+            module Connectors
+                private
+
+                def check_connectors(sec, rows, i)
+                    # Under a text row a stem may hang anywhere.
+                    return unless rows[i - 1].any? do |ch|
+                        arms(ch).positive? || SIDE_A.include?(ch)
+                    end
+
+                    rows[i].each_with_index do |ch, c|
+                        check_connector(sec, rows, i, [ch, c])
+                    end
+                end
+
+                def check_connector(sec, rows, i, glyph)
+                    ch, c = glyph
+                    ascii = connector_kind(rows[i], ch, c) or return
+                    above = Geometry.at(rows[i - 1], c)
+                    return if hangs?(above, ascii) ||
+                              crossing?(rows, i, c, above)
+
+                    report(sec, i, "connector '#{ch}' at col #{geo_col(c)} " \
+                                   "hangs from '#{above}'")
+                end
+
+                # The ASCII glyphs that may carry this connector (an
+                # arrow head's, or a vertical's), or nil when the glyph
+                # is no connector: a vertical with a horizontal beside it
+                # is a junction drawn in two cells.
+                def connector_kind(row, ch, c)
+                    return ABOVE_ARROW_A if arrow_head?(row, ch, c)
+                    return SIDE_A if arms?(ch, UP | DOWN, exact: true) &&
+                                     !beside_horizontal?(row, c)
+
+                    ABOVE_VERT_A if ch == "|" && !beside?(row, c, "-")
+                end
+
+                def hangs?(above, ascii)
+                    arms(above).anybits?(DOWN) || ascii.include?(above)
+                end
+
+                def arrow_head?(row, ch, c)
+                    ARROWS.include?(ch) || (ch == "v" && lone?(row, c))
+                end
+
+                def lone?(row, c)
+                    Geometry.at(row, c - 1) == " " &&
+                        Geometry.at(row, c + 1) == " "
+                end
+
+                def beside?(row, c, glyph)
+                    Geometry.at(row, c - 1) == glyph ||
+                        Geometry.at(row, c + 1) == glyph
+                end
+
+                def beside_horizontal?(row, c)
+                    [c - 1, c + 1].any? do |x|
+                        arms?(Geometry.at(row, x), LEFT | RIGHT, exact: true)
+                    end
+                end
+
+                # A lifeline crossed by an arrow: a plain horizontal
+                # above, the same vertical on the row above that.
+                def crossing?(rows, i, c, above)
+                    return false unless i >= 2 &&
+                                        arms?(above, LEFT | RIGHT, exact: true)
+
+                    hangs?(Geometry.at(rows[i - 2], c), SIDE_A)
+                end
+            end
+        end
+    end
+end

data/lib/tessella/lint/lines.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # The checks one line at a time: invalid UTF-8, tabs, forbidden
+        # sequences, trailing blanks, wide / invisible / emoji-capable /
+        # non-ASCII glyphs, spaces other than U+0020, wide glyphs on an
+        # aligned row (web) and ambiguous ones (cjk), and the column
+        # budget (prefix and suffix charged), which also records the
+        # line's ruler row.
+        module Lines
+            private
+
+            # A line that is not valid UTF-8 is named once, then linted
+            # with each bad byte as "?".
+            def sanitized(sec)
+                lines = sec.lines.each_with_index.map do |line, i|
+                    next line if line.valid_encoding?
+
+                    report(sec, i, "invalid UTF-8 byte sequence")
+                    line.scrub("?")
+                end
+                sec.with(lines: lines)
+            end
+
+            def check_line(sec, i, line)
+                report(sec, i, "tab character") if line.include?("\t")
+                check_forbidden(sec, i, line)
+                report(sec, i, "trailing whitespace") if
+                    line.match?(/[ \t]+\z/)
+                check_chars(sec, i, line)
+                check_target_row(sec, i, line)
+                check_budget(sec, i, line)
+            end
+
+            def check_forbidden(sec, i, line)
+                @opts[:forbid].each do |seq|
+                    if seq == :trailing_backslash
+                        if line.end_with?("\\")
+                            report(sec, i, "row ends in backslash (line " \
+                                           "splicing)")
+                        end
+                    elsif line.include?(seq)
+                        report(sec, i, "forbidden sequence #{seq.inspect}")
+                    end
+                end
+            end
+
+            def check_chars(sec, i, line)
+                skip = text_styled(line)
+                line.each_char.with_index do |ch, k|
+                    check_char(sec, i, ch) unless skip.include?(k)
+                end
+            end
+
+            # Under :web, an emoji-capable glyph followed by U+FE0E is
+            # kept as text: the indices of both, neither a finding.
+            def text_styled(line)
+                return [] unless @opts[:web]
+
+                line.enum_for(:scan, /(.)\u{FE0E}/).flat_map do
+                    match = Regexp.last_match
+                    k = match.begin(0)
+                    Lint.emoji_risk?(match[1].ord) ? [k, k + 1] : []
+                end
+            end
+
+            def check_char(sec, i, ch)
+                wide = Lint.wide?(ch.ord)
+                report(sec, i, glyph("wide char", ch)) if wide && no_wide?
+                check_blank(sec, i, ch)
+                check_web_char(sec, i, ch) if @opts[:web]
+                check_ascii_char(sec, i, ch) if @opts[:ascii] && !wide
+            end
+
+            # Names a glyph drawn as nothing, or as a blank that is not
+            # U+0020.
+            def check_blank(sec, i, ch)
+                if Lint.invisible?(ch.ord)
+                    report(sec, i, code_point("invisible char", ch))
+                elsif Lint.look_alike_space?(ch)
+                    report(sec, i, code_point("look-alike space", ch))
+                end
+            end
+
+            # A look-alike space is named by check_blank already.
+            def check_ascii_char(sec, i, ch)
+                return if ch.ord <= 0x7F || Lint.look_alike_space?(ch)
+
+                report(sec, i, glyph("non-ASCII", ch))
+            end
+
+            def check_budget(sec, i, line)
+                cols = end_column(line) + @tail
+                @rulers << Ruler.new(line: sec.first + i, width: cols,
+                                     verticals: vertical_columns(line))
+                return if cols <= @opts[:width]
+
+                report(sec, i, "#{cols} columns rendered (budget " \
+                               "#{@opts[:width]})")
+            end
+
+            def code_point(what, ch)
+                format("%<what>s U+%<code>04X", what: what, code: ch.ord)
+            end
+
+            def no_wide? = @opts[:no_wide] || @opts[:ascii]
+
+            def glyph(what, ch)
+                format("%<what>s U+%<code>04X %<ch>s", what: what,
+                                                       code: ch.ord, ch: ch)
+            end
+        end
+    end
+end

data/lib/tessella/lint/mixing.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # ASCII box structure and Unicode box drawing in one figure: a
+        # figure is a run of non-blank lines holding a box-drawing
+        # glyph (so a Markdown table beside it stays out), inline code
+        # spans stripped first (prose naming a glyph is not art). One
+        # finding per figure, at its first ASCII-structured line. An
+        # allow-mixed marker line closes the group before it and
+        # exempts the next group to form, however far below.
+        module Mixing
+            # A line using ASCII as structure: a pair from
+            # ASCII_STRUCT_PAIR, or a | at its first or last non-blank.
+            def self.ascii_structural?(line)
+                return true if line.match?(ASCII_STRUCT_PAIR)
+
+                trimmed = line.strip
+                !trimmed.empty? &&
+                    (trimmed.start_with?("|") || trimmed.end_with?("|"))
+            end
+
+            private
+
+            def check_vocab_mixing(sec)
+                group = []
+                exempt = sec.exempt
+                sec.lines.each_with_index do |line, i|
+                    next group << [i, line.gsub(INLINE_CODE, "")] unless
+                        line.match?(MIXED_MARKER) || line.strip.empty?
+
+                    exempt = flush_vocab_group(sec, group, exempt) ||
+                             line.match?(MIXED_MARKER)
+                    group = []
+                end
+                flush_vocab_group(sec, group, exempt)
+            end
+
+            # Checks the group unless exempt; an empty group (blank
+            # after blank, marker after marker) keeps the exemption.
+            def flush_vocab_group(sec, group, exempt)
+                return exempt if group.empty?
+
+                flag_mixed_vocab(sec, group) unless exempt
+                false
+            end
+
+            def flag_mixed_vocab(sec, group)
+                return unless group.any? { |_, line| line.match?(BOX_CHAR) }
+
+                i, = group.find { |_, line| Mixing.ascii_structural?(line) }
+                return unless i
+
+                report(sec, i, "ASCII structure (a +-/-+/--/|-/-|/+|/|+/->/" \
+                               "<- pair, or | at the line edge) mixed " \
+                               "with Unicode box-drawing (U+2500-257F) " \
+                               "in the same figure")
+            end
+        end
+    end
+end

data/lib/tessella/lint/runner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Tessella
+    module Lint
+        # One lint run over one text: splits it into sections (the
+        # whole text, or each fenced block), runs every check on each
+        # in artlint.rb's order -- line by line, then shadows, mixing,
+        # anchor drift, and geometry when asked -- and collects the
+        # findings and ruler rows.
+        class Runner
+            include Lines
+            include TargetRows
+            include Shadows
+            include Mixing
+            include Drift
+            include Geometry
+
+            def initialize(opts)
+                @opts = opts
+                @overhead = Lint.width_of(opts[:prefix])
+                @tail = Lint.width_of(opts[:suffix])
+                @findings = []
+                @rulers = []
+            end
+
+            def run(text)
+                lines = text.each_line.map(&:chomp)
+                sections(lines).each { check(it) }
+                Report.new(findings: @findings, rulers: @rulers)
+            end
+
+            private
+
+            # Fences are found on a scrubbed copy (a pattern cannot read
+            # an invalid byte), each section keeping its raw lines, so
+            # the bad byte is a finding there, not an abort.
+            def sections(lines)
+                whole = Section.new(lines: lines, first: 1, exempt: false)
+                return [whole] unless @opts[:fences]
+
+                scrubbed = lines.map { it.valid_encoding? ? it : it.scrub("?") }
+                Fences.sections(scrubbed).map do |sec|
+                    sec.with(lines: lines[sec.first - 1, sec.lines.size])
+                end
+            end
+
+            def check(sec)
+                sec = sanitized(sec)
+                sec.lines.each_with_index { |line, i| check_line(sec, i, line) }
+                check_shadows(sec)
+                check_vocab_mixing(sec) unless @opts[:allow_mixed]
+                check_anchor_drift(sec)
+                check_geometry(sec) if @opts[:geometry]
+            end
+
+            def report(sec, index, message)
+                @findings << Finding.new(line: sec.first + index,
+                                         message: message)
+            end
+
+            # A row's last display column: the prefix, then the row.
+            def end_column(line) = @overhead + Lint.width_of(line)
+
+            def vertical_columns(line)
+                col = @overhead
+                line.each_char.filter_map do |ch|
+                    col += Width.char(ch.ord)
+                    col if VERTICALS.include?(ch)
+                end
+            end
+        end
+    end
+end