slamdown 0.5.0

data/lib/slamdown/conversion/tables.rb

@@ -0,0 +1,676 @@
+# frozen_string_literal: true
+
+module Slamdown
+module Conversion
+
+# Interprets normalised table structure and expands cell spans before a renderer selects native syntax or canonical HTML.
+module Tables
+	STRUCTURAL_SEMANTICS = [:table, :table_head, :table_body, :table_foot, :table_row, :table_cell, :table_caption, :table_colgroup, :table_column].freeze
+	SPAN_ATTRIBUTES = ["colspan", "rowspan"].freeze
+	MAX_COLUMNS = 256
+	MAX_ROWS = 10_000
+	MAX_GRID_POSITIONS = 100_000
+	MAX_SPAN = 10_000
+
+	# Represents one source row before span expansion.
+	class Row
+		attr_reader :node, :cells
+
+		def initialize(node, cells)
+			@node = node
+			@cells = cells.freeze
+			freeze
+		end
+
+		def header?
+			!cells.empty? && cells.all? { |cell| cell.source_name == "th" }
+		end
+
+		# Coerces mistaken header cells to ordinary body cells without changing their normalised contents.
+		def as_body
+			body_cells = cells.map do |cell|
+				cell.source_name == "th" ? cell.with(:source_name => "td") : cell
+			end
+			self.class.new(node.with(:children => body_cells), body_cells)
+		end
+	end
+
+	# Represents either a source cell or an empty cell created by a source span.
+	class Cell
+		attr_reader :node, :placeholder_source
+
+		def initialize(node = nil, placeholder_source = nil, materialise = true)
+			@node = node
+			@placeholder_source = placeholder_source
+			@materialise = materialise
+			freeze
+		end
+
+		def placeholder?
+			node.nil?
+		end
+
+		def materialise?
+			@materialise
+		end
+	end
+
+	# Holds one format-specific grouping of a format-neutral source table after the shared grid algorithm has run.
+	class Layout
+		attr_reader :head_rows, :body_groups, :foot_rows, :complexity_reason
+
+		def initialize(head_rows, body_groups, foot_rows)
+			@ragged_padded = false
+			rows = head_rows + body_groups.flatten + foot_rows
+			if rows.length > MAX_ROWS
+				set_limited(:row_count)
+				return
+			end
+
+			expanded_by_row, @complexity_reason = expand(rows)
+			if complexity_limited?
+				set_empty_groups
+				freeze
+				return
+			end
+			expanded_by_row, @ragged_padded, padding_error = pad_ragged_rows(rows, expanded_by_row)
+			if padding_error
+				set_limited(padding_error)
+				return
+			end
+			@head_rows = map_rows(head_rows, expanded_by_row)
+			@body_groups = body_groups.map { |group| map_rows(group, expanded_by_row) }.freeze
+			@foot_rows = map_rows(foot_rows, expanded_by_row)
+			@expanded_by_node_id = rows.each_with_object({}) { |row, result| result[row.node.object_id] = expanded_by_row.fetch(row.object_id) }.freeze
+			freeze
+		end
+
+		def rows
+			head_rows + body_groups.inject([]) { |result, group| result + group } + foot_rows
+		end
+
+		def rectangular?
+			widths = rows.map(&:length)
+			!widths.empty? && widths.first > 0 && widths.uniq.length == 1 && rows.none? { |row| row.any?(&:nil?) }
+		end
+
+		def complexity_limited?
+			!complexity_reason.nil?
+		end
+
+		def ragged_padded?
+			@ragged_padded
+		end
+
+		def expanded_row(node)
+			@expanded_by_node_id[node.object_id]
+		end
+
+		private
+
+		# Tracks pending row spans as ranges, materialising cells only after every hard native-table gate has passed.
+		def expand(rows)
+			pending = []
+			positions = 0
+			result = {}
+			rows.each do |row|
+				expanded = []
+				next_pending = []
+				column_cursor = 0
+				pending.each do |first_column, last_column, remaining, source, materialise|
+					(first_column..last_column).each { |column| expanded[column] = Cell.new(nil, source, materialise) }
+					next_pending << [first_column, last_column, remaining - 1, source, materialise] if remaining > 1
+				end
+
+				row.cells.each do |cell_node|
+					column_span, column_error = span(cell_node, "colspan")
+					row_span, row_error = span(cell_node, "rowspan")
+					return [nil, column_error || row_error] if column_error || row_error
+
+					column = available_column(expanded, column_span, column_cursor)
+					return [nil, :column_count] if column + column_span > MAX_COLUMNS
+
+					expanded[column] = Cell.new(cell_node)
+					column_materialise = !Hash[cell_node.attributes].key?("colspan")
+					(1...column_span).each { |offset| expanded[column + offset] = Cell.new(nil, cell_node, column_materialise) }
+					if row_span > 1
+						row_materialise = !Hash[cell_node.attributes].key?("rowspan")
+						next_pending << [column, column + column_span - 1, row_span - 1, cell_node, row_materialise]
+					end
+					column_cursor = column + column_span
+				end
+
+				result[row.object_id] = expanded.freeze
+				positions += expanded.length
+				return [nil, :grid_positions] if positions > MAX_GRID_POSITIONS
+
+				pending = next_pending
+			end
+			[result.freeze, nil]
+		end
+
+		def available_column(expanded, width, starting_column)
+			column = starting_column
+			column += 1 until (column...(column + width)).all? { |candidate| expanded[candidate].nil? }
+			column
+		end
+
+		# Missing trailing cells are a common editor artefact; pad them only after the expanded grid remains within every safety gate.
+		def pad_ragged_rows(rows, expanded_by_row)
+			widths = rows.map { |row| expanded_by_row.fetch(row.object_id).length }
+			return [expanded_by_row, false, nil] if widths.uniq.length <= 1
+
+			width = widths.max
+			return [nil, false, :grid_positions] if width * rows.length > MAX_GRID_POSITIONS
+
+			padded = rows.each_with_object({}) do |row, result|
+				cells = expanded_by_row.fetch(row.object_id)
+				missing = width - cells.length
+				result[row.object_id] = (cells + Array.new(missing) { Cell.new }).freeze
+			end
+			[padded.freeze, true, nil]
+		end
+
+		def span(cell, name)
+			value = cell.semantic_values.fetch(:table_spans, {})[name]
+			return [1, nil] unless value.is_a?(String) && /\A\d+\z/.match(value.strip)
+
+			span = [value.to_i, 1].max
+			span > MAX_SPAN ? [nil, :span] : [span, nil]
+		end
+
+		def map_rows(rows, expanded_by_row)
+			rows.map { |row| expanded_by_row.fetch(row.object_id) }.freeze
+		end
+
+		def set_limited(reason)
+			@complexity_reason = reason
+			set_empty_groups
+			freeze
+		end
+
+		def set_empty_groups
+			@head_rows = [].freeze
+			@body_groups = [].freeze
+			@foot_rows = [].freeze
+			@expanded_by_node_id = {}.freeze
+		end
+	end
+
+	# Carries interpreted groups and the canonical HTML fallback tree for one normalised table.
+	class Analysis
+		attr_reader :table, :caption, :head_rows, :body_groups, :foot_rows, :html_required
+
+		def initialize(table, caption, head_rows, body_groups, foot_rows, html_required, captions_merged, dropped_spans)
+			@table = table
+			@caption = caption
+			@head_rows = head_rows.freeze
+			@body_groups = body_groups.map(&:freeze).freeze
+			@foot_rows = foot_rows.freeze
+			@html_required = html_required
+			@captions_merged = captions_merged
+			@dropped_spans = dropped_spans
+			@source_layout = Layout.new(head_rows, body_groups, foot_rows)
+			freeze
+		end
+
+		def html_required?
+			html_required
+		end
+
+		def captions_merged?
+			@captions_merged
+		end
+
+		# Header-cell inference differs only in how many leading all-header rows each output format can express.
+		def layout(format)
+			heads, bodies, feet = corrected_groups
+			if heads.empty? && !bodies.empty?
+				first_group = bodies.first
+				available = first_group.take_while(&:header?).length
+				inferred = format == "markdown" ? [available, 1].min : available
+				unless inferred.zero?
+					heads = first_group.first(inferred)
+					bodies = [first_group.drop(inferred)] + bodies.drop(1)
+					bodies.reject!(&:empty?)
+				end
+			end
+			bodies = [bodies.flatten] if format == "markdown" && bodies.length > 1
+			Layout.new(heads, bodies, feet)
+		end
+
+		# Produces the corrected structural tree used whenever table syntax falls back to canonical HTML.
+		def table_for(format)
+			children = @dropped_spans && !@source_layout.complexity_limited? ? materialise_dropped_spans(table.children) : table.children
+			children = merge_sections(children, :table_head)
+			children = merge_sections(children, :table_foot)
+			children = merge_sections(children, :table_body) if format == "markdown"
+			children = wrap_direct_rows(children)
+			children = coerce_bodyless_sections(children)
+			children = children.map { |child| canonicalise_fallback_node(child) }
+			children = canonical_table_order(children)
+			table.with(:children => children)
+		end
+
+		private
+
+		def materialise_dropped_spans(nodes)
+			nodes.map do |node|
+				if node.semantic_kind == :table_row
+					cells = @source_layout.expanded_row(node)
+					node.with(:children => cells ? materialised_cells(cells, node) : node.children)
+				else
+					node.with(:children => materialise_dropped_spans(node.children))
+				end
+			end
+		end
+
+		def materialised_cells(cells, row)
+			cells.each_with_object([]) do |cell, result|
+				if !cell.placeholder?
+					result << cell.node
+				elsif cell.materialise?
+					result << empty_cell(cell.placeholder_source || row.children.first, row.source_path)
+				end
+			end
+		end
+
+		def empty_cell(source, path)
+			factory = Normaliser::NodeFactory.new
+			factory.build(
+				:source_name => source && source.source_name == "th" ? "th" : "td",
+				:semantic_kind => :table_cell,
+				:category => :block,
+				:representation => :semantic,
+				:synthetic => true,
+				:source_path => path
+			)
+		end
+
+		def corrected_groups
+			heads = head_rows
+			bodies = body_groups
+			feet = foot_rows
+			return [heads, bodies, feet] unless bodies.empty?
+
+			if !heads.empty? && !feet.empty?
+				[heads, [feet], []]
+			elsif !heads.empty?
+				[[], [heads.map(&:as_body)], []]
+			elsif !feet.empty?
+				[[], [feet], []]
+			else
+				[heads, bodies, feet]
+			end
+		end
+
+		def merge_sections(children, semantic_kind)
+			sections = children.select { |child| child.semantic_kind == semantic_kind }
+			return children if sections.length < 2
+
+			merged = sections.first.with(:children => sections.map(&:children).flatten)
+			replaced = false
+			children.each_with_object([]) do |child, result|
+				if child.semantic_kind == semantic_kind
+					unless replaced
+						result << merged
+						replaced = true
+					end
+				else
+					result << child
+				end
+			end
+		end
+
+		def coerce_bodyless_sections(children)
+			return children if children.any? { |child| [:table_body, :table_row].include?(child.semantic_kind) }
+
+			head = children.find { |child| child.semantic_kind == :table_head }
+			foot = children.find { |child| child.semantic_kind == :table_foot }
+			section = foot || head
+			return children unless section
+
+			body = body_section(section, !head.nil? && foot.nil?)
+			children.map do |child|
+				if child.equal?(section)
+					body
+				elsif child.semantic_kind == :table_foot
+					nil
+				else
+					child
+				end
+			end.compact
+		end
+
+		def wrap_direct_rows(children)
+			result = []
+			rows = []
+			flush = lambda do
+				unless rows.empty?
+					factory = Normaliser::NodeFactory.new
+					result << factory.build(
+						:source_name => "tbody",
+						:semantic_kind => :table_body,
+						:category => :block,
+						:children => rows,
+						:representation => :semantic,
+						:synthetic => true,
+						:source_path => rows.first.source_path
+					)
+					rows = []
+				end
+			end
+
+			children.each do |child|
+				if child.semantic_kind == :table_row
+					rows << child
+				else
+					flush.call
+					result << child
+				end
+			end
+			flush.call
+			result
+		end
+
+		def canonicalise_fallback_node(node)
+			children = node.children.map { |child| canonicalise_fallback_node(child) }
+			if node.semantic_kind == :table_cell && children.length > 1 && children.all? { |child| child.category == :block }
+				factory = Normaliser::NodeFactory.new
+				wrapper = factory.build(
+					:source_name => "div",
+					:category => :block,
+					:children => children,
+					:representation => :html,
+					:source_path => children.first.source_path
+				)
+				children = [wrapper]
+			end
+			node.with(:children => children)
+		end
+
+		def canonical_table_order(children)
+			ranks = {
+				:table_caption => 0,
+				:table_colgroup => 1,
+				:table_column => 1,
+				:table_head => 2,
+				:table_body => 3,
+				:table_foot => 4
+			}
+			children.each_with_index.sort_by { |child, index| [ranks.fetch(child.semantic_kind, 5), index] }.map(&:first)
+		end
+
+		def body_section(section, coerce_header_cells)
+			rows = section.children.map do |row|
+				next row unless coerce_header_cells && row.semantic_kind == :table_row
+
+				cells = row.children.map do |cell|
+					cell.semantic_kind == :table_cell && cell.source_name == "th" ? cell.with(:source_name => "td") : cell
+				end
+				row.with(:children => cells)
+			end
+			section.with(
+				:source_name => "tbody",
+				:semantic_kind => :table_body,
+				:children => rows,
+				:representation => :semantic
+			)
+		end
+	end
+
+	# Reads table groups without rendering or mutating the normalised tree.
+	class Analyser
+		class << self
+			def analyse(table)
+				new.analyse(table)
+			end
+		end
+
+		def analyse(table)
+			raise ArgumentError, "table must be a normalised Slamdown table" unless table.is_a?(NormalisedNode) && table.semantic_kind == :table
+
+			@credible_width = credible_table_width(table)
+			table = sanitise_table_spans(table)
+			@html_required = structural_html_required?(table)
+			@captions = []
+			@head_rows = []
+			@body_groups = []
+			@foot_rows = []
+			@direct_rows = []
+			@dropped_spans = false
+			cleaned_children = table.children.each_with_object([]) do |child, children|
+				next if ignorable_whitespace?(child)
+
+				cleaned = clean_table_structure(child)
+				next unless cleaned
+
+				interpret_child(cleaned)
+				children << cleaned
+			end
+			flush_direct_rows
+			caption, cleaned_children, captions_merged = normalise_captions(cleaned_children)
+
+			Analysis.new(table.with(:children => cleaned_children), caption, @head_rows, @body_groups, @foot_rows, @html_required, captions_merged, @dropped_spans)
+		end
+
+		private
+
+		# Infers a safe width only from rows whose retained column spans are already within the hard expansion limit.
+		def credible_table_width(table)
+			widths = table_rows(table).map do |row|
+				cells = row.children.select { |child| child.semantic_kind == :table_cell }
+				next if cells.empty?
+
+				width = 0
+				credible = cells.all? do |cell|
+					value = Hash[cell.attributes]["colspan"]
+					if value.is_a?(String) && /\A\d+\z/.match(value.strip) && value.to_i > MAX_SPAN
+						false
+					else
+						width += valid_span(value)
+						true
+					end
+				end
+				width if credible && width <= MAX_COLUMNS
+			end.compact
+			widths.max
+		end
+
+		def table_rows(node)
+			result = node.semantic_kind == :table_row ? [node] : []
+			result + node.children.flat_map { |child| table_rows(child) }
+		end
+
+		def sanitise_table_spans(node)
+			children = node.children.map { |child| sanitise_table_spans(child) }
+			return node.with(:children => children) unless node.semantic_kind == :table_cell
+
+			attributes = node.attributes.dup
+			spans = node.semantic_values.fetch(:table_spans, {}).dup
+			["colspan", "rowspan"].each do |name|
+				retained = Hash[attributes][name]
+				unless retained
+					spans.delete(name)
+					next
+				end
+
+				value = retained.strip
+				if !/\A\d+\z/.match(value) || value.to_i < 1
+					attributes.reject! { |attribute_name, _attribute_value| attribute_name == name }
+					spans.delete(name)
+				elsif name == "colspan" && value.to_i > MAX_SPAN && @credible_width
+					clamped = @credible_width.to_s
+					attributes.map! { |attribute_name, attribute_value| [attribute_name, attribute_name == name ? clamped : attribute_value] }
+					spans[name] = clamped
+				else
+					spans[name] = value
+				end
+			end
+
+			semantic_values = node.semantic_values.merge(:table_spans => spans)
+			semantic_values = semantic_values.reject { |name, value| name == :table_spans && value.empty? }
+			node.with(:attributes => attributes, :children => children, :semantic_values => semantic_values)
+		end
+
+		def valid_span(value)
+			return 1 unless value.is_a?(String) && /\A\d+\z/.match(value.strip) && value.to_i > 0
+
+			value.to_i
+		end
+
+		def interpret_child(child)
+			case child.semantic_kind
+			when :table_caption
+				@captions << child
+				@html_required ||= structural_html_required?(child)
+			when :table_head
+				flush_direct_rows
+				@head_rows.concat(rows(child))
+				@html_required ||= structural_html_required?(child)
+			when :table_body
+				flush_direct_rows
+				group = rows(child)
+				@body_groups << group unless group.empty?
+				@html_required ||= structural_html_required?(child)
+			when :table_foot
+				flush_direct_rows
+				@foot_rows.concat(rows(child))
+				@html_required ||= structural_html_required?(child)
+			when :table_row
+				@direct_rows << row(child)
+			when :table_colgroup, :table_column
+				@html_required ||= meaningful_column?(child)
+			else
+				@html_required = true
+			end
+		end
+
+		# Duplicate plain captions are editor debris; merge only where no rich structure or retained metadata can be lost.
+		def normalise_captions(children)
+			return [nil, children, false] if @captions.empty?
+			return [@captions.first, children, false] if @captions.length == 1
+			unless @captions.all? { |caption| mergeable_caption?(caption) }
+				@html_required = true
+				return [@captions.first, children, false]
+			end
+
+			factory = Normaliser::NodeFactory.new
+			content = Normaliser::Content.new(factory)
+			combined = []
+			@captions.each_with_index do |caption, index|
+				combined << factory.text(" ", caption.source_path) unless index.zero?
+				combined.concat(caption.children)
+			end
+			merged = @captions.first.with(:children => content.normalise_inline_sequence(combined, :trim => true))
+			[merged, replace_captions(children, merged), true]
+		end
+
+		def mergeable_caption?(caption)
+			caption.representation == :semantic && !caption.id && caption.classes.empty? && caption.attributes.empty? && caption.children.none? { |child| child.category == :block }
+		end
+
+		def replace_captions(children, merged)
+			inserted = false
+			children.each_with_object([]) do |child, result|
+				if child.semantic_kind == :table_caption
+					unless inserted
+						result << merged
+						inserted = true
+					end
+				else
+					result << child
+				end
+			end
+		end
+
+		def rows(section)
+			section.children.each_with_object([]) do |child, result|
+				next if ignorable_whitespace?(child)
+
+				if child.semantic_kind == :table_row
+					result << row(child)
+				else
+					@html_required = true
+				end
+			end
+		end
+
+		def row(node)
+			@html_required ||= structural_html_required?(node)
+			cells = node.children.each_with_object([]) do |child, result|
+				next if ignorable_whitespace?(child)
+
+				if child.semantic_kind == :table_cell
+					@html_required ||= structural_html_required?(child)
+					@dropped_spans ||= dropped_span?(child)
+					result << child
+				else
+					@html_required = true
+				end
+			end
+			Row.new(node, cells)
+		end
+
+		def flush_direct_rows
+			return if @direct_rows.empty?
+
+			@body_groups << @direct_rows
+			@direct_rows = []
+		end
+
+		def structural_html_required?(node)
+			return true if node.representation == :html
+			return false if node.semantic_kind == :table && node.representation == :semantic
+			return false unless STRUCTURAL_SEMANTICS.include?(node.semantic_kind)
+
+			attributes = node.attributes.reject { |name, _value| node.semantic_kind == :table_cell && name == "scope" }
+			!attributes.empty?
+		end
+
+		def dropped_span?(node)
+			retained = Hash[node.attributes]
+			node.semantic_values.fetch(:table_spans, {}).keys.any? { |name| !retained.key?(name) }
+		end
+
+		def ignorable_whitespace?(node)
+			node.kind == :text && node.value.to_s.strip.empty?
+		end
+
+		def clean_table_structure(node)
+			cleaned = clean_column_structure(node)
+			return unless cleaned
+			return cleaned unless STRUCTURAL_SEMANTICS.include?(cleaned.semantic_kind)
+
+			children = cleaned.children.reject { |child| ignorable_whitespace?(child) }.map { |child| clean_table_structure(child) }.compact
+			cleaned.with(:children => children)
+		end
+
+		def meaningful_column?(node)
+			own_meaningful_column?(node) || node.children.any? { |child| meaningful_column?(child) }
+		end
+
+		def own_meaningful_column?(node)
+			return true if node.representation == :html
+
+			attributes = node.attributes.reject { |name, _value| name == "span" }
+			node.id || !node.classes.empty? || !attributes.empty?
+		end
+
+		def clean_column_structure(node)
+			return node unless [:table_colgroup, :table_column].include?(node.semantic_kind)
+			return if !meaningful_column?(node)
+			return node unless node.semantic_kind == :table_colgroup
+
+			children = node.children.map { |child| clean_column_structure(child) }.compact
+			changes = {:children => children}
+			unless own_meaningful_column?(node)
+				changes[:attributes] = node.attributes.reject { |name, _value| name == "span" }
+			end
+			node.with(changes)
+		end
+	end
+end
+
+end
+end

data/lib/slamdown/conversion.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "conversion/configuration"
+require_relative "conversion/configuration_validator"
+require_relative "conversion/policy"
+require_relative "conversion/prepared_node"
+require_relative "conversion/semantic_extractor"
+require_relative "conversion/preparer"
+require_relative "conversion/normalised_node"
+require_relative "conversion/normalisation"
+require_relative "conversion/normaliser/correction_diagnostics"
+require_relative "conversion/normaliser/node_factory"
+require_relative "conversion/normaliser/content"
+require_relative "conversion/normaliser/breaks"
+require_relative "conversion/normaliser/heading_levels"
+require_relative "conversion/normaliser/url_rewriter"
+require_relative "conversion/normaliser/inline_semantics"
+require_relative "conversion/normaliser/element_actions"
+require_relative "conversion/normaliser"
+require_relative "conversion/tables"
+require_relative "conversion/rendering/entity_encoder"
+require_relative "conversion/rendering/escaper"
+require_relative "conversion/rendering/html"
+require_relative "conversion/rendering/strategy"
+require_relative "conversion/rendering/result"
+require_relative "conversion/renderer"
+require_relative "conversion/converter"
+
+module Slamdown
+module Conversion
+end
+end