qss 0.1.0

data/lib/qss/qss_native_auditor.rb

@@ -0,0 +1,908 @@
+require 'nokogiri'
+require 'yaml'
+
+module QSS
+  class QssNativeAuditor
+    # rubocop:disable all -- generated by exe/qss-sync; its layout is the generator's, not the house style
+    # QSS-GENERATED-BEGIN (exe/qss-sync rewrites everything below, up to the closing marker)
+    # GENERATED FROM grammar.yml - DO NOT EDIT
+    PAYLOAD_TAGS = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "span", "label", "blockquote", "li"].freeze
+
+    AUDITOR_CONFIG = {"id_prefix"=>"", "structural_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "narrow_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "icon_prefixes"=>[], "registry_path"=>"", "portal_root"=>""}.freeze
+    # QSS-GENERATED-END
+    # rubocop:enable all
+
+    # The effective settings: the core defaults above (AUDITOR_CONFIG, generated from grammar.yml alone) with the
+    # consuming project's config over them, read at runtime (QSS.configure, lib/qss/configuration.rb).
+    def self.settings
+      QSS.configuration.auditor_settings(AUDITOR_CONFIG)
+    end
+
+    # The project's interim id prefix ("" = no prefix convention).
+    def self.id_prefix(settings = self.settings)
+      settings['id_prefix'].to_s
+    end
+
+    # Narrow list: keywords that MANDATE 'contain: layout'
+    def self.narrow_structural_pattern(settings = self.settings)
+      /\b(#{settings['narrow_words'].map { |w| Regexp.escape(w) }.join('|')})\b/i
+    end
+
+    def self.portal_label(settings = self.settings)
+      settings['portal_root'].to_s.empty? ? 'the overlay portal root' : settings['portal_root']
+    end
+
+    # INTERIM (decision 2, part 3): an id carrying the project's own prefix is structural, exactly as before item B.
+    # Only reached for ids the id check exempts; everything else is decided by IdRules.
+    def self.structural_id?(id, prefix = id_prefix)
+      !prefix.empty? && id.start_with?(prefix)
+    end
+
+    # Escape hatches
+    ESCAPE_HATCHES = [ 'foreign', 'qss-payload-override', 'qss-content-driven' ].freeze
+
+    # Name rules for the OPEN vocabularies (qualifiers, qss-function values, custom type names):
+    # a closed alphabet plus drift detection. Pure functions: nothing here reads a file or the DOM.
+    # Design: architecture-decisions-2026-09-16.md section 11 and the item B decisions in the roadmap.
+    module NameRules
+      SHAPE = /\A[a-z]+(?:-[a-z]+)*\z/
+      SHAPE_WITH_DIGITS = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+      ANCHOR = 'QSSObject'.freeze
+      SUFFIXES = %w[ing es ed s].freeze
+      INVISIBLE = /[\u00AD\u200B-\u200F\u2060\uFEFF]/
+      LEET = { '4' => %w[a], '3' => %w[e], '1' => %w[i l], '0' => %w[o], '5' => %w[s],
+               '7' => %w[t], '8' => %w[b], '@' => %w[a], '$' => %w[s] }.freeze
+      # Best-effort Cyrillic/Greek lookalikes for the letters of the anchor. The real defence against
+      # homoglyphs is the closed alphabet (anything non-ASCII is rejected outright); this only lets the
+      # anchor near-miss check give a specific message.
+      CONFUSABLES = { "\u0430" => 'a', "\u0435" => 'e', "\u043E" => 'o', "\u0441" => 'c', "\u0455" => 's',
+                      "\u0456" => 'i', "\u0458" => 'j', "\u051B" => 'q', "\u0405" => 'S', "\u041E" => 'O',
+                      "\u03BF" => 'o', "\u039F" => 'O' }.freeze
+
+      # nil when the value is acceptable, otherwise a symbol saying why not.
+      def self.rejection_reason(value, allow_digits: false)
+        return :empty unless value.is_a?(String) && !value.empty?
+        return :invisible if value.match?(INVISIBLE)
+        return :non_ascii if value.match?(/[^\x00-\x7F]/)
+        return :uppercase if value.match?(/[A-Z]/)
+        return :underscore if value.include?('_')
+        return :digit if !allow_digits && value.match?(/\d/)
+        return :hyphen_placement if value.match?(/\A-|-\z|--/)
+        return :too_short if value.delete('-').length < 3
+        (allow_digits ? SHAPE_WITH_DIGITS : SHAPE).match?(value) ? nil : :invalid_character
+      end
+
+      def self.valid?(value, allow_digits: false)
+        rejection_reason(value, allow_digits: allow_digits).nil?
+      end
+
+      # Every reading of a leetspeak string (1 can be i or l), capped so it cannot blow up.
+      def self.leet_variants(value)
+        variants = [ '' ]
+        value.each_char do |ch|
+          options = LEET[ch] || [ ch ]
+          variants = variants.flat_map { |v| options.map { |o| v + o } }.first(16)
+        end
+        variants.uniq
+      end
+
+      # Registered names the candidate is suspiciously close to, as [name, reason] pairs. An exact match
+      # is not "similar" (it is accepted), and nothing here ever merges or rewrites a name.
+      def self.similar(candidate, existing_names, allow_digits: false)
+        existing_names.filter_map do |name|
+          next if name == candidate
+          reason = similarity_reason(candidate, name, allow_digits: allow_digits)
+          [ name, reason ] if reason
+        end
+      end
+
+      def self.similarity_reason(candidate, name, allow_digits:)
+        if allow_digits && candidate.match?(/\d/)
+          return :numeronym if numeronym?(candidate, name)
+          variants = leet_variants(candidate)
+          return :leetspeak if variants.include?(name)
+          # After folding, only the strong rules apply: the weak ones (subsequence...) on folded text just make noise.
+          variants.each { |v| reason = plain_reason(v, name, strong_only: true); return reason if reason }
+          return nil
+        end
+        plain_reason(candidate, name)
+      end
+
+      # First match wins, and only sets the label in the message. Order: a one-or-two-letter slip first, then the
+      # composed canonical form (word order, endings and dropped vowels all at once), then the loose abbreviation
+      # checks (the weakest, skipped after leetspeak folding).
+      def self.plain_reason(a, b, strong_only: false)
+        return :edit_distance if osa_distance(a, b) <= ([ a.length, b.length ].max <= 5 ? 1 : 2)
+        return :canonical_form if canonical(a).length >= 2 && canonical(a) == canonical(b)
+        return :initialism if !strong_only && (initialism?(a, b) || initialism?(b, a))
+        return :subsequence if !strong_only && (subsequence?(a, b) || subsequence?(b, a))
+        nil
+      end
+
+      def self.words(name)
+        name.split('-')
+      end
+
+      # One form for comparing names that differ by word order, common endings or dropped vowels:
+      # stem each word, drop its vowels after the first letter (collapsing doubled letters), sort the words.
+      # save-file, file-save and sv-fl all become fl-sv; deleting, delete and dlt all become dlt.
+      def self.canonical(name)
+        words(name).map { |w| strip_vowels(stem_word(w)) }.sort.join('-')
+      end
+
+      def self.strip_vowels(word)
+        word[0].to_s + word[1..].to_s.delete('aeiou').squeeze
+      end
+
+      # Strip one common ending (and a silent final e): delete/deleting/deleted -> delet.
+      def self.stem_word(word)
+        suffix = SUFFIXES.find { |x| word.end_with?(x) && word.length - x.length >= 3 }
+        (suffix ? word[0...-suffix.length] : word).chomp('e')
+      end
+
+      # cta == call-to-action: the short form is the first letters of the long name's words.
+      def self.initialism?(short, long)
+        parts = words(long)
+        parts.size > 1 && short == parts.map { |w| w[0] }.join
+      end
+
+      # i18n, a11y, k8s: first letter + count of the letters between + last letter.
+      def self.numeronym?(candidate, name)
+        m = candidate.match(/\A([a-z])(\d+)([a-z])\z/)
+        m && name.match?(/\A[a-z]+\z/) && name[0] == m[1] && name[-1] == m[3] && name.length == m[2].to_i + 2
+      end
+
+      # Weaker check for abbreviations that lose consonants too: cfg is inside config.
+      def self.subsequence?(short, long)
+        return false unless short.length >= 3 && short.length < long.length && short[0] == long[0]
+        rest = long.each_char
+        short.each_char.all? { |c| loop { return false unless (l = rest.next rescue nil); break if l == c }; true }
+      end
+
+      # Edit distance where swapping two neighbouring letters counts as one edit (form/from).
+      def self.osa_distance(a, b)
+        rows = Array.new(a.length + 1) { |i| [ i ] + [ 0 ] * b.length }
+        (0..b.length).each { |j| rows[0][j] = j }
+        (1..a.length).each do |i|
+          (1..b.length).each do |j|
+            cost = a[i - 1] == b[j - 1] ? 0 : 1
+            rows[i][j] = [ rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost ].min
+            if i > 1 && j > 1 && a[i - 1] == b[j - 2] && a[i - 2] == b[j - 1]
+              rows[i][j] = [ rows[i][j], rows[i - 2][j - 2] + 1 ].min
+            end
+          end
+        end
+        rows[a.length][b.length]
+      end
+
+      # Case, leetspeak and lookalike-character folding, for the anchor near-miss check.
+      def self.fold_lookalikes(str)
+        s = str.gsub(INVISIBLE, '')
+        s = s.unicode_normalize(:nfkc) rescue s
+        s.each_char.map { |c| CONFUSABLES[c] || c }.join.downcase
+      end
+
+      # True when a segment of the id is NOT the exact anchor but reads like it once case, leetspeak and
+      # lookalikes are folded (or is one edit away): QssObject, QSSObjct, QSS0bject, a Cyrillic o...
+      def self.anchor_near_miss?(id)
+        return false unless id.is_a?(String)
+        segments = id.split('-')
+        candidates = segments + (segments.size >= 2 ? [ segments.last(2).join ] : [])
+        candidates.any? do |cand|
+          next false if cand == ANCHOR
+          leet_variants(fold_lookalikes(cand)).any? { |v| osa_distance(v, ANCHOR.downcase) <= 1 }
+        end
+      end
+    end
+    # The closed vocabulary of native base objects (all HTML element names, plus the svg/math roots).
+    # Convention, fixed by the W3C spec and NOT configurable (architecture doc 11.6). Also the closed list a
+    # `qss-relation` value is checked against. The base object of a native id is its last hyphen segment.
+    NATIVE_TAGS = %w[
+      a abbr address area article aside audio b base bdi bdo blockquote body br button canvas caption cite
+      code col colgroup data datalist dd del details dfn dialog div dl dt em embed fieldset figcaption figure
+      footer form h1 h2 h3 h4 h5 h6 head header hgroup hr html i iframe img input ins kbd label legend li link
+      main map mark math menu meta meter nav noscript object ol optgroup option output p picture pre progress q
+      rp rt ruby s samp script search section select selectedcontent slot small source span strong style sub summary sup svg
+      table tbody td template textarea tfoot th thead time title tr track u ul var video wbr
+    ].freeze
+
+    # The native tags that are structural frames by convention (decision 2, part 1). To be confirmed by Kraig.
+    STRUCTURAL_NATIVE_TAGS = %w[header footer nav aside main section article dialog form].freeze
+
+    # The CSS length units, from MDN's <length> reference (49). Percentages, times, angles, flex fractions and
+    # resolutions are NOT lengths and are deliberately absent. Used to recognise a raw CSS length in a value.
+    LENGTH_UNITS = %w[cap ch em ex ic lh rcap rch rem rex ric rlh vh svh lvh dvh vw svw lvw dvw vmax svmax lvmax dvmax
+                      vmin svmin lvmin dvmin vb svb lvb dvb vi svi lvi dvi cqw cqh cqi cqb cqmin cqmax px cm mm q in pc pt].freeze
+
+    # Essential dimensional facts (architecture doc 11.7) are exact and mathematical, written in QSS's OWN units,
+    # never in raw CSS units: a whole number of QSS units (1..1000, the w[N] / h[N] scale), a percentage in 0.1
+    # steps (the w-pct[N] scale, up to 100%), or, for aspect-ratio, a ratio of two whole numbers.
+    module Dimensions
+      PERCENT = /\A(\d{1,3})(?:\.(\d))?%\z/
+      RATIO = /\A(\d+)\s*\/\s*(\d+)\z/
+
+      # Returns [normalized, nil] or [nil, "what is wrong"].
+      def self.parse(key, raw)
+        return parse_ratio(raw) if key == 'aspect-ratio'
+        return parse_units(raw) if raw.is_a?(Integer)
+        return [ nil, "must be a whole number of QSS units or a percentage, not #{raw.inspect}" ] unless raw.is_a?(String)
+        text = raw.strip
+        if (m = text.match(PERCENT))
+          pct = "#{m[1]}.#{m[2] || 0}".to_f
+          return [ { kind: :percent, value: pct }, nil ] if pct.positive? && pct <= 100
+          return [ nil, 'a percentage must be above 0 and at most 100' ]
+        end
+        unit = LENGTH_UNITS.find { |u| text.downcase.match?(/\A[\d.]+#{u}\z/) }
+        return [ nil, "#{text.inspect} uses the CSS unit #{unit}; declare QSS units (a whole number) or a percentage" ] if unit
+        return [ nil, "#{text.inspect} is qualitative; an essential dimension must be an exact number" ] if text.match?(/\A[a-z-]+\z/i)
+        [ nil, "must be a whole number of QSS units or a percentage, not #{raw.inspect}" ]
+      end
+
+      def self.parse_units(int)
+        int.between?(1, 1000) ? [ { kind: :units, value: int }, nil ] : [ nil, "QSS units run from 1 to 1000, not #{int}" ]
+      end
+
+      def self.parse_ratio(raw)
+        m = raw.is_a?(String) && raw.match(RATIO)
+        return [ nil, "must be a ratio of two whole numbers like \"16 / 9\", not #{raw.inspect}" ] unless m && m[1].to_i.positive? && m[2].to_i.positive?
+        [ { kind: :ratio, value: [ m[1].to_i, m[2].to_i ] }, nil ]
+      end
+
+      # ---- enforcement: an element of a type with declared dimensions must not set a conflicting value ----
+
+      SIZE_CLASS = /\A(w|h)\[(\d+)\]\z/
+      PCT_CLASS = /\A(w|h)-pct\[(\d+)\]\z/
+      FULL_CLASS = /\A(w|h)-(?:full|f)\z/
+
+      # The QSS size utilities on an element's classes, in the declaration's own units:
+      # w[N] / h[N] are QSS units, w-pct[N] is N/10 percent, w-full and w-f are 100%. Responsive variants
+      # (md:w[..]) and anything else are ignored. Returns { 'width' => [facts], 'height' => [facts] }.
+      def self.from_classes(classes)
+        found = Hash.new { |h, k| h[k] = [] }
+        classes.each do |cls|
+          base = cls.sub(/\Aqss-/, '')
+          axis = ->(letter) { letter == 'w' ? 'width' : 'height' }
+          if (m = base.match(SIZE_CLASS))
+            found[axis.(m[1])] << { kind: :units, value: m[2].to_i, from: cls }
+          elsif (m = base.match(PCT_CLASS))
+            found[axis.(m[1])] << { kind: :percent, value: m[2].to_i / 10.0, from: cls }
+          elsif (m = base.match(FULL_CLASS))
+            found[axis.(m[1])] << { kind: :percent, value: 100.0, from: cls }
+          end
+        end
+        found
+      end
+
+      # The axes an element's classes leave undeclared, width before height (empty when both are declared).
+      def self.missing_axes(classes)
+        found = from_classes(classes)
+        %w[width height].reject { |axis| found.key?(axis) }
+      end
+
+      def self.describe(fact)
+        case fact[:kind]
+        when :units then "#{fact[:value]} QSS units"
+        when :percent then "#{fact[:value] == fact[:value].to_i ? fact[:value].to_i : fact[:value]}%"
+        when :ratio then fact[:value].join(' / ')
+        end
+      end
+
+      # Messages for every way the element's classes contradict the type's declared dimensions.
+      def self.conflicts(declared, classes, type_name)
+        found = from_classes(classes)
+        messages = []
+        %w[width height].each do |key|
+          want = declared[key]
+          next unless want
+          found[key].each do |have|
+            same = have[:kind] == want[:kind] && (have[:value] - want[:value]).abs < 1e-9
+            next if same
+            messages << "#{type_name.inspect} declares #{key} #{describe(want)}, but this element sets #{describe(have)} (#{have[:from]})"
+          end
+        end
+        ratio = declared['aspect-ratio']
+        if ratio && found['width'].size == 1 && found['height'].size == 1
+          w, h = found['width'].first, found['height'].first
+          if w[:kind] == :units && h[:kind] == :units && w[:value] * ratio[:value][1] != h[:value] * ratio[:value][0]
+            messages << "#{type_name.inspect} declares aspect-ratio #{describe(ratio)}, but #{w[:from]} with #{h[:from]} is #{w[:value]} / #{h[:value]}"
+          end
+        end
+        messages
+      end
+    end
+
+    # Foreign content (third-party or framework markup inside a QSS page: blog text, Tailwind, ...) is exempt from
+    # the frame rules but not from this one: any RAW CSS LENGTH in an arbitrary value or an inline style must be in
+    # rem. Percentages are allowed; every other length unit (the closed MDN list minus rem) is a violation.
+    # Named framework utilities (text-lg, p-4) carry no unit in their name and are the framework's business.
+    # Time, angle, flex and resolution values (300ms, 17deg, 1fr) are not lengths and pass.
+    module Units
+      NON_REM = (LENGTH_UNITS - [ 'rem' ]).freeze
+      # A number that is a whole token: not part of a word or a hex colour (the lookbehind), and the unit ends it.
+      LENGTH = /(?<![A-Za-z0-9#.])(\d*\.?\d+)(#{NON_REM.join('|')})(?![A-Za-z0-9])/i
+
+      # Quoted strings and url(...) contents are text, not values.
+      def self.strip_literals(text)
+        text.to_s.gsub(/url\([^)]{0,300}\)/i, 'url()').gsub(/'[^']{0,300}'/, "''").gsub(/"[^"]{0,300}"/, '""')
+      end
+
+      # The raw non-rem lengths in a class token or a style attribute, as "11px" strings.
+      def self.violations(text)
+        strip_literals(text).scan(LENGTH).map { |number, unit| "#{number}#{unit}" }
+      end
+
+      EXACT_PX = { 'px' => 1.0, 'pt' => 96.0 / 72, 'pc' => 16.0, 'in' => 96.0, 'cm' => 96.0 / 2.54, 'mm' => 96.0 / 25.4, 'q' => 96.0 / 101.6 }.freeze
+      FONT_RELATIVE = %w[em ex ch cap ic lh rcap rch rex ric rlh].freeze
+      CONTAINER = %w[cqw cqh cqi cqb cqmin cqmax].freeze
+
+      # What to write instead, for the message. Absolute units convert exactly (at the default 16px root font
+      # size); font-relative ones depend on the element's own font; viewport and container units are relative to
+      # something rem and % cannot name.
+      def self.hint(value)
+        m = value.to_s.match(/\A(-?\d*\.?\d+)([a-z]+)\z/i)
+        return nil unless m
+        number, unit = m[1].to_f, m[2].downcase
+        if EXACT_PX.key?(unit)
+          rem = (number * EXACT_PX[unit] / 16.0).round(4)
+          "#{value} = #{rem == rem.to_i ? rem.to_i : rem}rem at the default 16px root size"
+        elsif FONT_RELATIVE.include?(unit)
+          "#{unit} depends on the element's own font, so it has no exact rem equivalent; choose a rem value"
+        elsif CONTAINER.include?(unit)
+          "#{unit} is relative to a container, which rem and % cannot express"
+        else
+          "#{unit} is relative to the viewport, which rem and % cannot express (a whole-viewport size has a named utility such as h-dvh or min-h-svh)"
+        end
+      end
+
+      # On QSS STRUCTURE (a QSS actor outside foreign content) the rule is stricter: ANY raw CSS length, rem
+      # included, is a second unit system next to QSS's own. Structure is sized in QSS units (calc(N * var(--qnt)),
+      # w[N], h[N]) or in the canvas grid (w-pct[N], h-pct[N]). Percentages and non-lengths still pass.
+      LENGTH_ANY = /(?<![A-Za-z0-9#.])(\d*\.?\d+)(#{LENGTH_UNITS.join('|')})(?![A-Za-z0-9])/i
+      VIEWPORT = %w[vh svh lvh dvh vw svw lvw dvw vmin svmin lvmin dvmin vmax svmax lvmax dvmax vb svb lvb dvb vi svi lvi dvi].freeze
+
+      def self.violations_any(text)
+        strip_literals(text).scan(LENGTH_ANY).map { |number, unit| "#{number}#{unit}" }
+      end
+
+      def self.qss_hint(value)
+        m = value.to_s.match(/\A(-?\d*\.?\d+)([a-z]+)\z/i)
+        return nil unless m
+        number, unit = m[1], m[2].downcase
+        if VIEWPORT.include?(unit)
+          "viewport units never appear in QSS structure; use the canvas grid (h-pct[N] or w-pct[N], N in 0.1% steps)"
+        elsif unit == 'px'
+          "QSS structure is sized in QSS units, and 1 unit is 1/1000 of the canvas width, so it scales with the canvas: #{number}px is not simply #{number}; pick the units for the intended proportion (calc(N * var(--qnt)), w[N], h[N])"
+        else
+          "#{unit} is not a QSS unit; use QSS units (calc(N * var(--qnt)), w[N], h[N]) or a named utility"
+        end
+      end
+    end
+
+
+    # A consumer's vocabulary, read at runtime from a YAML file (decision 3):
+    #
+    #   allow_digits: false            # optional, per-project opt-in for digits in open names
+    #   functions: [save, delete]      # the open qss-function vocabulary
+    #   types:                         # entries record ONLY what a type ADDS (deltas, decision 4b)
+    #     divider-hr:                  #   native extension: {qualifier}-{nativeTag}
+    #       dimensions:                #   exact facts in QSS units (whole number), a percentage, or a ratio
+    #         height: 1
+    #     workspace-QSSObject:         #   custom type: {qualifier}-QSSObject
+    #       structural: true
+    #
+    # (qss-function and qss-relation are ELEMENT attributes, not type facts, so they are not declared here.)
+    #
+    # A missing file is an empty registry. A malformed one is an empty registry that carries an error, so the
+    # audit can report it rather than crash. Everything here is a plain value: no side effects but the cache.
+    class Registry
+      TOP_LEVEL_KEYS = %w[allow_digits functions types].freeze
+      ENTRY_KEYS = %w[extends structural dimensions notes].freeze
+      DIMENSION_KEYS = %w[width height aspect-ratio].freeze
+      # Named only so the error can say WHY: these are accidental (presentational/positional), never essential.
+      PRESENTATIONAL_KEYS = %w[color background background-color border border-radius padding margin font font-size
+                               font-weight position top left right bottom z-index opacity shadow box-shadow display
+                               gap radius].freeze
+      CACHE = {}
+
+      attr_reader :allow_digits, :functions, :types, :errors, :warnings
+
+      def self.load(path)
+        path = path.to_s
+        return new({}) if path.empty? || !File.exist?(path)
+        mtime = File.mtime(path)
+        cached = CACHE[path]
+        return cached.last if cached && cached.first == mtime
+        registry = begin
+          new(YAML.safe_load(File.read(path), permitted_classes: [], aliases: false))
+        rescue Psych::Exception => e
+          new({}, load_error: "#{File.basename(path)} is not valid YAML: #{e.message.lines.first.to_s.strip}")
+        end
+        CACHE[path] = [ mtime, registry ]
+        registry
+      end
+
+      def initialize(data, load_error: nil)
+        @errors = []
+        @warnings = []
+        @types = {}
+        @functions = []
+        @allow_digits = false
+        return add_error(:malformed, load_error) if load_error
+        data = {} if data.nil?
+        return add_error(:malformed, 'the registry must be a mapping with allow_digits, functions and types') unless data.is_a?(Hash)
+        (data.keys.map(&:to_s) - TOP_LEVEL_KEYS).each do |key|
+          add_error(:unknown_key, "unknown top-level key #{key.inspect} (allowed: #{TOP_LEVEL_KEYS.join(', ')})")
+        end
+        read_allow_digits(data['allow_digits'])
+        read_functions(data['functions'])
+        read_types(data['types'])
+        check_extends
+      end
+
+      def empty?
+        @types.empty? && @functions.empty?
+      end
+
+      def function?(name)
+        @functions.include?(name)
+      end
+
+      def type?(name)
+        @types.key?(name)
+      end
+
+      # Registered type names by kind, so an id is only compared against names of its own kind.
+      def custom_type_names
+        @types.keys.select { |n| base_of(n) == :qss_object }
+      end
+
+      def native_type_names
+        @types.keys.reject { |n| base_of(n) == :qss_object }
+      end
+      # Is this registered type a structural frame? Its own declaration wins, then what it extends; a native
+      # extension falls back to whether its base tag is structural by convention.
+      def structural?(name, seen = [])
+        entry = @types[name]
+        return false if entry.nil? || seen.include?(name)
+        return entry['structural'] if entry.key?('structural')
+        parent = entry['extends']
+        return structural?(parent, seen + [ name ]) if parent && @types.key?(parent)
+        STRUCTURAL_NATIVE_TAGS.include?(base_of(name))
+      end
+
+      # The exact dimensional facts a type has, its own declarations over whatever it extends:
+      # { 'height' => { kind: :units, value: 1 } }. Only valid declarations are returned.
+      def dimensions_of(name, seen = [])
+        entry = @types[name]
+        return {} if entry.nil? || seen.include?(name)
+        parent = entry['extends']
+        inherited = parent && @types.key?(parent) ? dimensions_of(parent, seen + [ name ]) : {}
+        own = (entry['dimensions'].is_a?(Hash) ? entry['dimensions'] : {}).each_with_object({}) do |(key, raw), out|
+          parsed, problem = Dimensions.parse(key.to_s, raw)
+          out[key.to_s] = parsed if parsed && !problem
+        end
+        inherited.merge(own)
+      end
+
+      # The native tag a type ultimately builds on, or :qss_object for a custom type.
+      def base_of(name)
+        return :qss_object if name.to_s.end_with?("-#{NameRules::ANCHOR}")
+        name.to_s.split('-').last
+      end
+
+      private
+
+      def add_error(code, message)
+        @errors << { code: code, message: message }
+        nil
+      end
+
+      def add_warning(code, message)
+        @warnings << { code: code, message: message }
+      end
+
+      def read_allow_digits(value)
+        return if value.nil?
+        return @allow_digits = value if value == true || value == false
+        add_error(:bad_allow_digits, "allow_digits must be true or false, not #{value.inspect}")
+      end
+
+      def read_functions(list)
+        return if list.nil?
+        return add_error(:bad_functions, 'functions must be a list of names') unless list.is_a?(Array)
+        list.each do |name|
+          reason = NameRules.rejection_reason(name, allow_digits: @allow_digits)
+          next add_error(:invalid_name, "function #{name.inspect} is not an acceptable name (#{reason})") if reason
+          next add_error(:duplicate, "function #{name.inspect} is listed twice") if @functions.include?(name)
+          NameRules.similar(name, @functions, allow_digits: @allow_digits).each do |other, why|
+            add_warning(:similar_registered, "function #{name.inspect} looks like #{other.inspect} (#{why}); confirm they are different")
+          end
+          @functions << name
+        end
+      end
+
+      def read_types(map)
+        return if map.nil?
+        return add_error(:bad_types, 'types must be a mapping of type name to what it adds') unless map.is_a?(Hash)
+        map.each do |name, entry|
+          name = name.to_s
+          problem = type_name_problem(name)
+          next add_error(:invalid_type_name, "type #{name.inspect}: #{problem}") if problem
+          entry = {} if entry.nil?
+          next add_error(:bad_entry, "type #{name.inspect} must be a mapping (or empty)") unless entry.is_a?(Hash)
+          @types[name] = read_entry(name, entry.transform_keys(&:to_s))
+        end
+      end
+
+      def read_entry(name, entry)
+        entry.each_key do |key|
+          if DIMENSION_KEYS.include?(key)
+            add_error(:dimension_outside_dimensions, "type #{name.inspect}: declare #{key.inspect} under dimensions:, in QSS units")
+          elsif PRESENTATIONAL_KEYS.include?(key)
+            add_error(:presentational_fact, "type #{name.inspect}: #{key.inspect} is presentational or positional, so it is never an essential fact (use a class)")
+          elsif !ENTRY_KEYS.include?(key)
+            add_error(:unknown_type_key, "type #{name.inspect}: unknown key #{key.inspect} (allowed: #{ENTRY_KEYS.join(', ')})")
+          end
+        end
+        if entry.key?('structural') && ![ true, false ].include?(entry['structural'])
+          add_error(:bad_structural, "type #{name.inspect}: structural must be true or false")
+        end
+        read_dimensions(name, entry['dimensions']) if entry.key?('dimensions')
+        entry
+      end
+
+      def read_dimensions(name, value)
+        return add_error(:bad_dimensions, "type #{name.inspect}: dimensions must be a mapping of #{DIMENSION_KEYS.join(', ')}") unless value.is_a?(Hash)
+        value.each do |key, raw|
+          key = key.to_s
+          next add_error(:unknown_dimension, "type #{name.inspect}: #{key.inspect} is not a declarable dimension (allowed: #{DIMENSION_KEYS.join(', ')})") unless DIMENSION_KEYS.include?(key)
+          _parsed, problem = Dimensions.parse(key, raw)
+          add_error(:bad_dimension, "type #{name.inspect}: #{key}: #{problem}") if problem
+        end
+      end
+
+      # nil when the name is well formed: {qualifier}-QSSObject or {qualifier}-{nativeTag}.
+      def type_name_problem(name)
+        if name.include?(NameRules::ANCHOR)
+          return "the anchor #{NameRules::ANCHOR} must appear once, as the last segment" unless name.end_with?("-#{NameRules::ANCHOR}") && name.scan(NameRules::ANCHOR).size == 1
+          qualifier = name.delete_suffix("-#{NameRules::ANCHOR}")
+        else
+          return 'looks like a broken QSSObject anchor' if NameRules.anchor_near_miss?(name)
+          qualifier, _, tag = name.rpartition('-')
+          return "must be {qualifier}-{nativeTag} or {qualifier}-#{NameRules::ANCHOR}; #{tag.inspect} is not a native tag" unless NATIVE_TAGS.include?(tag)
+          return 'a qualifier is required (a bare native tag needs no registration)' if qualifier.empty?
+        end
+        reason = NameRules.rejection_reason(qualifier, allow_digits: @allow_digits)
+        reason ? "the qualifier #{qualifier.inspect} is not acceptable (#{reason})" : nil
+      end
+
+      def check_extends
+        @types.each do |name, entry|
+          parent = entry['extends']
+          next if parent.nil?
+          unless parent.is_a?(String) && (NATIVE_TAGS.include?(parent) || @types.key?(parent))
+            next add_error(:unknown_extends, "type #{name.inspect} extends #{parent.inspect}, which is neither a native tag nor a registered type")
+          end
+          unless base_of(parent) == base_of(name)
+            add_error(:mismatched_base, "type #{name.inspect} cannot extend #{parent.inspect}: they build on different base objects")
+          end
+        end
+        @types.each_key do |name|
+          chain = [ name ]
+          cursor = @types[name]['extends']
+          while cursor && @types.key?(cursor)
+            if chain.include?(cursor)
+              add_error(:extends_cycle, "types #{(chain + [ cursor ]).join(' -> ')} extend each other in a loop")
+              break
+            end
+            chain << cursor
+            cursor = @types[cursor]['extends']
+          end
+        end
+      end
+    end
+    # The id check (decisions 2 and 4b), a pure function over one id. It BIFURCATES on a single boolean:
+    # does the id contain the literal anchor QSSObject?
+    #   yes -> custom-type branch, committed: exact shape {qualifier}-QSSObject, or a red error (never falls through)
+    #   no  -> native branch: an id with the project's interim prefix (its id_prefix) or the framework prefix (qss-) is
+    #          exempt (the caller applies its interim rules); otherwise the last hyphen segment must be a native tag
+    # Severities: RED means a rule is violated (look closer: fix the markup, or amend the theory);
+    # ORANGE means a judgment call the rules cannot settle (a look-alike name, a probable broken anchor).
+    module IdRules
+      FRAMEWORK_PREFIX = 'qss-'.freeze
+      Result = Struct.new(:branch, :type_name, :qualifier, :base, :structural, :findings, keyword_init: true)
+
+      def self.check(id, registry:, exempt_prefixes: [])
+        id = id.to_s
+        return build(:none) if id.empty?
+        id.include?(NameRules::ANCHOR) ? check_custom(id, registry) : check_native(id, registry, exempt_prefixes)
+      end
+
+      def self.build(branch, **fields)
+        Result.new(branch: branch, findings: [], **fields)
+      end
+
+      def self.finding(code, severity, message)
+        { code: code, severity: severity, message: message }
+      end
+
+      def self.check_custom(id, registry)
+        result = build(:custom, type_name: id, base: :qss_object)
+        unless id.end_with?("-#{NameRules::ANCHOR}") && id.scan(NameRules::ANCHOR).size == 1
+          result.findings << finding(:malformed_anchor, 'red', "#{id.inspect}: the anchor #{NameRules::ANCHOR} must appear once, as the last segment ({qualifier}-#{NameRules::ANCHOR})")
+          return result
+        end
+        result.qualifier = id.delete_suffix("-#{NameRules::ANCHOR}")
+        reason = NameRules.rejection_reason(result.qualifier, allow_digits: registry.allow_digits)
+        return with(result, finding(:invalid_qualifier, 'red', "#{id.inspect}: the qualifier #{result.qualifier.inspect} is not acceptable (#{reason})")) if reason
+        if registry.type?(id)
+          result.structural = registry.structural?(id)
+        else
+          result.structural = false
+          register_or_similar(result, id, registry.custom_type_names, registry)
+        end
+        result
+      end
+
+      def self.check_native(id, registry, exempt_prefixes)
+        return build(:exempt, type_name: id) if exempt_prefixes.any? { |p| !p.to_s.empty? && id.start_with?(p) }
+        if NameRules.anchor_near_miss?(id)
+          return with(build(:native, type_name: id), finding(:broken_anchor, 'orange', "#{id.inspect} looks like a broken #{NameRules::ANCHOR} anchor; write it exactly, or drop it"))
+        end
+        qualifier, _, base = id.rpartition('-')
+        result = build(:native, type_name: id, qualifier: qualifier, base: base)
+        unless NATIVE_TAGS.include?(base)
+          return with(result, finding(:unknown_base_object, 'red', "#{id.inspect}: #{base.inspect} is not a native base object; an id reads {qualifier}-{nativeTag} or {qualifier}-#{NameRules::ANCHOR}"))
+        end
+        result.structural = STRUCTURAL_NATIVE_TAGS.include?(base)
+        return with(result, finding(:missing_qualifier, 'red', "#{id.inspect} is a bare native tag; say which one ({qualifier}-#{base})")) if qualifier.empty?
+        reason = NameRules.rejection_reason(qualifier, allow_digits: registry.allow_digits)
+        return with(result, finding(:invalid_qualifier, 'red', "#{id.inspect}: the qualifier #{qualifier.inspect} is not acceptable (#{reason})")) if reason
+        if registry.type?(id)
+          result.structural = registry.structural?(id)
+        else
+          register_or_similar(result, id, registry.native_type_names, registry)
+        end
+        result
+      end
+
+      # An unregistered type is an empty identity claim: point at the near match if there is one.
+      def self.register_or_similar(result, id, known, registry)
+        near = NameRules.similar(id, known, allow_digits: registry.allow_digits)
+        if near.empty?
+          kind = result.branch == :custom ? 'declare it as a type' : "register what #{result.qualifier.inspect} adds to #{result.base.inspect}, or drop the qualifier"
+          result.findings << finding(result.branch == :custom ? :undeclared_type : :unregistered_qualifier, 'red', "#{id.inspect} is not in the registry: #{kind}")
+        else
+          list = near.map { |name, why| "#{name.inspect} (#{why})" }.join(', ')
+          result.findings << finding(:similar_type, 'orange', "#{id.inspect} is not in the registry but looks like #{list}; confirm they differ, or fix the name")
+        end
+      end
+
+      def self.with(result, finding)
+        result.findings << finding
+        result
+      end
+    end
+    # The relational and functional facts of an element are plain attributes, not part of its id (decision 4b):
+    # qss-relation="form" names the larger structure it belongs to, qss-function="delete" what it does.
+    # Both are optional; only QSS actors are checked. Severity follows the scheme: red = a rule is violated,
+    # orange = a judgment call (a look-alike of a registered function).
+    module AttributeRules
+      def self.finding(code, severity, message)
+        { code: code, severity: severity, message: message }
+      end
+
+      def self.check(function:, relation:, registry:)
+        findings = []
+        findings.concat(check_function(function, registry)) if function
+        findings.concat(check_relation(relation)) if relation
+        findings
+      end
+
+      # The open vocabulary: closed alphabet, then the registry, then look-alikes of registered names.
+      def self.check_function(value, registry)
+        reason = NameRules.rejection_reason(value, allow_digits: registry.allow_digits)
+        return [ finding(:invalid_function, 'red', "qss-function #{value.inspect} is not an acceptable name (#{reason})") ] if reason
+        return [] if registry.function?(value)
+        near = NameRules.similar(value, registry.functions, allow_digits: registry.allow_digits)
+        if near.empty?
+          [ finding(:unregistered_function, 'red', "qss-function #{value.inspect} is not in the registry: register it, or use a registered function") ]
+        else
+          list = near.map { |name, why| "#{name.inspect} (#{why})" }.join(', ')
+          [ finding(:similar_function, 'orange', "qss-function #{value.inspect} is not in the registry but looks like #{list}; confirm they differ, or use the registered name") ]
+        end
+      end
+
+      # The closed vocabulary: the same native base-object list an id is checked against.
+      def self.check_relation(value)
+        return [] if NATIVE_TAGS.include?(value)
+        hint = NameRules.similar(value.to_s, NATIVE_TAGS).first(2).map(&:first)
+        [ finding(:bad_relation, 'red', "qss-relation #{value.inspect} is not a native base object#{hint.empty? ? '' : " (did you mean #{hint.map(&:inspect).join(' or ')}?)"}") ]
+      end
+    end
+    def self.audit_file(file_path)
+      return { status: 'grey', issues: [] } unless File.exist?(file_path)
+      raw_content = File.read(file_path).force_encoding('UTF-8').scrub rescue ""
+      return { status: 'grey', issues: [] } if raw_content.strip.empty?
+
+      issues = []
+
+      # Global checks
+      if raw_content.include?('!important')
+        issues << { type: 'protocol', message: "Cheat detected: '!important' is forbidden", severity: 'red' }
+      end
+
+      # Template parsing
+      doc_content = raw_content.gsub(/<%.*?%>/m, '<!--ERB-->')
+      # A fragment parse silently drops <html>, <head> and <body> (and their attributes), so a full document, such as
+      # a layout, is parsed as a document; anything else stays a fragment.
+      doc = doc_content.match?(/<(?:html|head|body)\b/i) ? Nokogiri::HTML(doc_content) : Nokogiri::HTML.fragment(doc_content)
+
+      # Item B: the consumer's registry (empty when none is configured) and the id rules.
+      settings = self.settings
+      prefix = id_prefix(settings)
+      narrow_pattern = narrow_structural_pattern(settings)
+      portal_label = portal_label(settings)
+      registry = Registry.load(settings['registry_path'])
+      exempt_prefixes = [ prefix, IdRules::FRAMEWORK_PREFIX ]
+      seen_ids = {}
+      seen_attributes = {}
+      unless registry.errors.empty?
+        issues << { type: 'identity', code: :registry_problem, message: "Registry problem (#{registry.errors.size}): #{registry.errors.first[:message]}", severity: 'red' }
+      end
+
+      doc.traverse do |node|
+        next unless node.element?
+
+        id = node['id'] || ""
+        classes = node['class']&.split(/\s+/) || []
+        style = node['style'] || ""
+
+        # The id rules apply to QSS actors (class `qss`); ids on other elements (third-party markup, framework or
+        # form-helper ids) are not ours to police. Ids with an exempt prefix still take the interim rules.
+        qss_actor = classes.include?('qss')
+        exempt_id = exempt_prefixes.any? { |p| !p.to_s.empty? && id.start_with?(p) }
+        identity = id.empty? || id.include?('<!--ERB-->') || !(qss_actor || exempt_id) ? nil : IdRules.check(id, registry: registry, exempt_prefixes: exempt_prefixes)
+        is_structural = identity.nil? ? false : (identity.branch == :exempt ? structural_id?(id, prefix) : identity.structural == true)
+        is_narrow_structural = is_structural && id.match?(narrow_pattern)
+        is_portal = id.include?('portal')
+        is_content_driven = classes.include?('qss-content-driven')
+
+        # Foreign context check
+        is_foreign = classes.include?('foreign') || classes.include?('qss-payload-override') ||
+                     node.ancestors.any? { |a| (a['class']&.split(/\s+/) || []).intersect?([ 'foreign', 'qss-payload-override' ]) }
+
+        # Foreign hygiene (item B): raw CSS lengths in arbitrary values and inline styles must be rem.
+        if is_foreign
+          (classes.select { |c| c.include?('[') }.flat_map { |c| Units.violations(c).map { |v| [ v, c ] } } + Units.violations(style).map { |v| [ v, "style=\"#{style}\"" ] }).each do |value, where|
+            issues << { type: 'protocol', code: :foreign_unit, message: "Foreign Unit Violation: #{value} in #{where} is a raw CSS length; foreign content may use rem or % only (#{Units.hint(value)})", severity: 'red' }
+          end
+        end
+
+        # QSS structure (item B): no raw CSS lengths at all; structure is sized in QSS units or the canvas grid.
+        if qss_actor && !is_foreign
+          (classes.select { |c| c.include?('[') }.flat_map { |c| Units.violations_any(c).map { |v| [ v, c ] } } + Units.violations_any(style).map { |v| [ v, "style=\"#{style[0, 60]}\"" ] }).each do |value, where|
+            issues << { type: 'protocol', code: :qss_unit, message: "QSS Unit Violation: #{value} in #{where} is a raw CSS length on QSS structure; #{Units.qss_hint(value)}", severity: 'red' }
+          end
+        end
+
+        next if is_foreign && !is_structural # Skip internal payload of foreign components
+
+        # Identity findings (item B), each id reported once per file.
+        if identity && !seen_ids[id]
+          seen_ids[id] = true
+          identity.findings.each { |f| issues << { type: 'identity', code: f[:code], message: f[:message], severity: f[:severity] } }
+        end
+
+        # Declared essential dimensions (item B): a registered type's exact facts must not be contradicted by the element.
+        if identity && registry.type?(id)
+          Dimensions.conflicts(registry.dimensions_of(id), classes, id).each do |message|
+            issues << { type: 'identity', code: :dimension_conflict, message: message, severity: 'red' }
+          end
+        end
+
+        # Relational and functional attributes (item B), on QSS actors only, each distinct pair once per file.
+        if qss_actor && (node['qss-function'] || node['qss-relation'])
+          pair = [ node['qss-function'], node['qss-relation'] ]
+          unless seen_attributes[pair]
+            seen_attributes[pair] = true
+            AttributeRules.check(function: pair[0], relation: pair[1], registry: registry).each do |f|
+              issues << { type: 'identity', code: f[:code], message: f[:message], severity: f[:severity] }
+            end
+          end
+        end
+
+        # Rule 5: Legacy Style Ban & Reactive Properties
+        if !style.empty?
+          # Split styles and check for static vs reactive
+          style_pairs = style.split(';').map(&:strip).reject(&:empty?)
+          style_pairs.each do |pair|
+            prop, val = pair.split(':', 2).map(&:strip)
+            next if prop.start_with?('--') # Reactive/Custom property allowed
+
+            # Special case: contain: layout in style is RED (Rule 1 / Rule 5)
+            if prop == 'contain' && val == 'layout'
+              issues << { type: 'protocol', message: "Legacy Style Violation: 'contain: layout' on ##{id} must be a class, not inline style.", severity: 'red' }
+            else
+              issues << { type: 'protocol', message: "Protocol Violation: Static inline style '#{prop}' forbidden on <#{node.name}#{id.empty? ? '' : '#' + id}>.", severity: 'red' }
+            end
+          end
+        end
+
+        # Explicit dimensions (every QSS actor): the core reset gives each actor `flex-shrink: 0; height: auto`, so an
+        # actor without a declared width and height takes its content's size and can overflow a bounded frame unseen.
+        # Declared = a core size class (Dimensions.from_classes); the opt-out is `qss-content-driven`. Class lists
+        # built in ERB are skipped: their classes cannot be known from the template.
+        actor_dimensions_checked = qss_actor && !is_foreign && !is_content_driven && !node['class'].include?('<!--ERB-->')
+        if actor_dimensions_checked
+          missing = Dimensions.missing_axes(classes)
+          unless missing.empty?
+            label = id.empty? ? "<#{node.name}>" : "##{id}"
+            issues << { type: 'protocol', code: :implicit_dimension, message: "Implicit Dimension Violation: QSS actor #{label} declares no #{missing.join(' and no ')}; declare it with a QSS size class (w[N]/h[N], w-pct[N]/h-pct[N], w-full/h-full) or opt out with qss-content-driven", severity: 'red' }
+          end
+        end
+
+        if is_structural
+          # Rule 1: Steel Frame Isolation (Narrow List)
+          if is_narrow_structural && !is_portal
+            unless classes.include?('contain-layout') || classes.include?('qss-contain-layout')
+              # We also check if it's currently in style (handled by Rule 5 above as RED)
+              # If it's missing entirely:
+              unless style.match?(/contain\s*:\s*layout/i)
+                issues << { type: 'protocol', message: "Steel Frame Violation: Structural element ##{id} must carry 'contain-layout' class.", severity: 'red' }
+              end
+            end
+          end
+
+          # Rule 2: Explicit Dimensions (structural elements the actor check above did not cover: non-actors, foreign or ERB-built)
+          unless is_content_driven || is_portal || actor_dimensions_checked
+            has_w = classes.any? { |c| c.match?(/^(w-|qss-w-)(full|half|\[|[\d.]+)/) || c.include?('var(--') }
+            has_h = classes.any? { |c| c.match?(/^(h-|qss-h-)(full|half|\[|[\d.]+)/) || c.include?('var(--') }
+
+            # Explicitly reject legacy bracket-DSL w[640] as invalid for Rule 2
+            # (The regex above allows w-[...] or w-full, but not w[...])
+
+            unless has_w && has_h
+              issues << { type: 'protocol', message: "Implicit Dimension Warning: Structural element ##{id} lacks explicit width/height classes.", severity: 'orange' }
+            end
+          end
+        end
+
+        # Rule 3: Portal Integrity (Extended)
+        has_z_class = classes.any? { |c| c.match?(/^(qss-)?z-\[?\d+\]?/) }
+        has_z_style = style.match?(/z-index\s*:/i)
+
+        if (has_z_class || has_z_style) && !is_portal && !is_foreign
+           issues << { type: 'protocol', message: "Portal Integrity Violation: z-index on <#{node.name}#{id.empty? ? '' : '#' + id}> outside #{portal_label}.", severity: 'red' }
+        end
+
+        # Rule 4: Payload Purity
+        if PAYLOAD_TAGS.include?(node.name) && !is_structural
+          style_pairs = style.split(';').map(&:strip).reject(&:empty?)
+          style_pairs.each do |pair|
+            prop, _ = pair.split(':', 2).map(&:strip)
+            if [ 'width', 'height', 'position' ].include?(prop.downcase)
+              issues << { type: 'protocol', message: "Payload Purity Violation: <#{node.name}> setting structural geometry '#{prop}' via style.", severity: 'red' }
+            end
+          end
+
+          # Also check for absolute/pos classes on payload
+          if classes.any? { |c| c.match?(/^(absolute|pos-|qss-absolute|qss-pos-)/) }
+             issues << { type: 'protocol', message: "Payload Purity Violation: <#{node.name}> carrying structural positioning classes.", severity: 'red' }
+          end
+        end
+      end
+
+      status = issues.any? { |i| i[:severity] == 'red' } ? 'red' : (issues.any? { |i| i[:severity] == 'orange' } ? 'orange' : 'green')
+      { status: status, issues: issues }
+    end
+
+    def self.report(file_path)
+      result = audit_file(file_path)
+      puts "Audit: #{file_path} [#{result[:status].upcase}]"
+      result[:issues].each do |issue|
+        puts "  [#{issue[:severity].upcase}] #{issue[:type]}: #{issue[:message]}"
+      end
+    end
+  end
+end