qss 0.1.0

data/lib/qss/configuration.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module QSS
+  # The consuming project's QSS settings, read at runtime. QSS core ships only neutral defaults (generated from
+  # grammar.yml into each auditor's AUDITOR_CONFIG); a consumer declares its own root and config file once:
+  #
+  #   QSS.configure(root: "/path/to/project", config: "config/myapp/qss_config.yml")
+  #
+  # Relative paths (the config file, and paths inside it such as auditor.registry_path) resolve against that
+  # root, never the process working directory. Without QSS.configure, the root is Rails.root when a Rails app
+  # is loaded; with neither, relative paths fall back to the working directory (a last resort, not a contract).
+  class Configuration
+    attr_reader :root, :config_path
+
+    def initialize(root: nil, config: nil)
+      @root = root && File.expand_path(root.to_s)
+      @config_path = config && resolve(config.to_s)
+      @cache = {}
+    end
+
+    def root_or_default
+      return @root if @root
+      return File.expand_path(Rails.root.to_s) if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      nil
+    end
+
+    # A relative path is resolved against the project root (File.expand_path keeps an absolute one as it is).
+    def resolve(path)
+      path = path.to_s
+      return "" if path.empty?
+      base = root_or_default
+      base ? File.expand_path(path, base) : File.expand_path(path)
+    end
+
+    # The consumer's config file as a Hash ({} when none is configured or the file is missing). Re-read when the
+    # file changes.
+    def consumer
+      return {} unless @config_path && File.exist?(@config_path)
+
+      mtime = File.mtime(@config_path)
+      @cache = { mtime: mtime, data: (YAML.load_file(@config_path) || {}) } unless @cache[:mtime] == mtime
+      @cache[:data]
+    end
+
+    # Auditor settings: the core defaults with the consumer's `auditor:` block over them. The overlay portal root
+    # comes from the consumer's `config.portal_root` (shared with the SCSS side); registry_path is resolved.
+    def auditor_settings(defaults)
+      data = consumer
+      settings = deep_merge(defaults, data["auditor"] || {})
+      portal = data.dig("config", "portal_root")
+      settings["portal_root"] = portal.to_s unless portal.nil?
+      settings["registry_path"] = resolve(settings["registry_path"])
+      settings.freeze
+    end
+
+    # The consumer's additions to the adjective categories (grammar_extensions: { category => [names] }).
+    def grammar_extensions
+      consumer["grammar_extensions"] || {}
+    end
+
+    private
+
+    def deep_merge(base, over)
+      return over unless base.is_a?(Hash) && over.is_a?(Hash)
+
+      base.merge(over) { |_key, a, b| deep_merge(a, b) }
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure(root:, config: nil)
+      @configuration = Configuration.new(root: root, config: config)
+    end
+  end
+end

data/lib/qss/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module QSS
+  # The Rails integration: a plain engine (no routes, controllers or models) so a Rails app finds QSS's assets
+  # (app/assets/stylesheets/qss/*, app/assets/javascripts/qss/*) through its asset pipeline. lib/qss.rb loads this
+  # file only when Rails is present; the auditors and configuration work without Rails.
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/qss/qss_auditor.rb

@@ -0,0 +1,412 @@
+require 'nokogiri'
+require 'json'
+
+module QSS
+  class QssAuditor
+    # 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
+    DSL_WHITELIST = [
+      'absolute',
+      'anchored',
+      'around',
+      'bg',
+      'bg-alpha',
+      'blend',
+      'blur',
+      'border',
+      'border-alpha',
+      'border-b',
+      'border-l',
+      'border-r',
+      'border-t',
+      'bright',
+      'busy',
+      'centered',
+      'clickable',
+      'contain',
+      'contrast',
+      'cover',
+      'cursor-col-resize',
+      'cursor-row-resize',
+      'detached',
+      'dev-border',
+      'evenly',
+      'flex',
+      'flex-1',
+      'flex-auto',
+      'flex-col',
+      'flex-none',
+      'flex-nowrap',
+      'flex-row',
+      'flex-wrap',
+      'floating',
+      'font-black',
+      'font-bold',
+      'font-medium',
+      'font-mono',
+      'font-sans',
+      'foreign',
+      'ghost',
+      'grayscale',
+      'grid',
+      'group',
+      'h-end',
+      'h-f',
+      'h-full',
+      'h-mid',
+      'h-start',
+      'horizontal',
+      'hue',
+      'icon-size',
+      'invert',
+      'invisible',
+      'italic',
+      'items-center',
+      'justify-between',
+      'justify-center',
+      'leading',
+      'lowercase',
+      'nowrap',
+      'opacity',
+      'outline-none',
+      'pos',
+      'pos-b',
+      'pos-r',
+      'pos-x',
+      'pos-y',
+      'qss',
+      'qss-content-driven',
+      'qss-dampen-scaling',
+      'qss-ergonomic-override',
+      'qss-legibility-override',
+      'qss-payload-override',
+      'relative',
+      'resize',
+      'ring',
+      'rounded',
+      'rounded-full',
+      'saturate',
+      'scroll',
+      'scroll-smooth',
+      'sepia',
+      'shadow',
+      'smooth',
+      'spaced',
+      'stuck',
+      'table-fixed',
+      'text-alpha',
+      'text-size',
+      'tracking',
+      'tracking-tighter',
+      'tracking-wide',
+      'tracking-wider',
+      'tracking-widest',
+      'transition-all',
+      'transition-colors',
+      'transition-none',
+      'truncate',
+      'underline',
+      'unselectable',
+      'uppercase',
+      'v-end',
+      'v-mid',
+      'v-start',
+      'vertical',
+      'visible',
+      'w-f',
+      'w-full'
+    ].freeze
+
+    PAYLOAD_TAGS = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "span", "label", "blockquote", "li"].freeze
+
+    ADJECTIVE_CATEGORIES = {"positional"=>["detached", "floating", "stuck", "absolute", "pos-x", "pos-y", "pos-r", "pos-b", "pos"], "flow_relative"=>["anchored", "relative"], "layout"=>["vertical", "horizontal", "centered", "v-mid", "h-mid", "v-start", "v-end", "h-start", "h-end", "spaced", "around", "evenly", "flex", "flex-col", "flex-row", "flex-wrap", "flex-nowrap", "flex-1", "flex-auto", "flex-none", "items-center", "justify-center", "justify-between", "grid", "table-fixed", "w-full", "h-full", "w-f", "h-f"], "typographic"=>["italic", "uppercase", "lowercase", "underline", "nowrap", "truncate", "font-mono", "font-sans", "font-medium", "font-bold", "font-black", "text-size", "leading", "tracking", "tracking-tighter", "tracking-wide", "tracking-wider", "tracking-widest", "icon-size"], "visual"=>["bg", "border", "border-t", "border-b", "border-l", "border-r", "rounded", "rounded-full", "shadow", "opacity", "blur", "bright", "contrast", "grayscale", "hue", "invert", "saturate", "sepia", "blend", "contain", "cover", "visible", "invisible", "bg-alpha", "border-alpha", "text-alpha"], "interactive"=>["clickable", "smooth", "busy", "ghost", "unselectable", "scroll-smooth", "scroll", "cursor-col-resize", "cursor-row-resize", "transition-all", "transition-colors", "transition-none", "ring", "resize", "outline-none"], "internal"=>["qss", "dev-border", "group", "foreign", "qss-legibility-override", "qss-ergonomic-override", "qss-payload-override", "qss-dampen-scaling", "qss-content-driven"]}.freeze
+
+    ILLEGAL_COMBOS = [{"tag_in"=>"payload_tags", "forbid_category"=>"positional", "severity"=>"red", "message"=>"Protocol Violation: Payload tags (<tag>) cannot carry flow-breaking positional adjectives. Use a wrapping <div> Frame.", "escape_hatch"=>"qss-payload-override"}].freeze
+
+    BLUEPRINT_NAMES = [].freeze
+
+    BLUEPRINT_SLOTS = {}.freeze
+
+    BRAND_COLORS = {"black"=>"#000000", "white"=>"#ffffff", "transparent"=>"transparent", "none"=>"none", "slate-50"=>"#f8fafc", "slate-100"=>"#f1f5f9", "slate-200"=>"#e2e8f0", "slate-300"=>"#cbd5e1", "slate-400"=>"#94a3b8", "slate-500"=>"#64748b", "slate-600"=>"#475569", "slate-700"=>"#334155", "slate-800"=>"#1e293b", "slate-900"=>"#0f172a", "slate-950"=>"#020617", "rose-500"=>"#f43f5e"}.freeze
+
+    DEPTHS = {"canvas"=>0, "content"=>100, "ui"=>500, "overlay"=>900, "modal"=>1000}.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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+    # Thresholds based on QSS Spec
+    LEGIBILITY_FLOOR = 11
+ERGONOMIC_MIN = 44
+
+# Core's own grammar, found relative to this file (not the working directory).
+GRAMMAR_PATH = File.expand_path('../../config/grammar.yml', __dir__)
+
+# 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
+
+# Everything derived from the settings, built once per audited file.
+Rules = Struct.new(:id_prefix, :structural_id_pattern, :narrow_id_pattern, :icon_prefix_pattern, :portal_label, :whitelist)
+
+def self.rules(settings = self.settings)
+  prefix = settings['id_prefix'].to_s
+  words = ->(key) { settings[key].map { |w| Regexp.escape(w) }.join('|') }
+  extensions = QSS.configuration.grammar_extensions.values.flatten
+  Rules.new(
+    prefix,
+    /^#{Regexp.escape(prefix)}.*(#{words.('structural_words')})/i,
+    /^#{Regexp.escape(prefix)}.*(#{words.('narrow_words')})/i,
+    settings['icon_prefixes'].empty? ? nil : /^(#{words.('icon_prefixes')})/,
+    settings['portal_root'].to_s.empty? ? 'the overlay portal root' : settings['portal_root'],
+    extensions.empty? ? DSL_WHITELIST : (DSL_WHITELIST + extensions).uniq
+  )
+end
+
+# An empty id_prefix means "no prefix convention": nothing counts as prefixed/first-party by prefix.
+def self.prefixed_id?(id, prefix = rules.id_prefix)
+  !prefix.empty? && id.start_with?(prefix)
+end
+
+def self.first_party?(id, classes, prefix = rules.id_prefix)
+  (!prefix.empty? && (id.start_with?(prefix) || classes.any? { |c| c.start_with?(prefix) })) ||
+    classes.any? { |c| c.start_with?('qss-') }
+end
+
+    # Whitelists
+
+
+
+    def self.audit_file(file_path)
+      file_path = file_path.to_s # callers pass Pathname (specs) or String
+      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?
+
+      # 0. Blueprint Integrity & Blast Radius Check (Global)
+      issues = []
+      r = rules
+      is_shared_definition = file_path.match?(/qss-objects\.json|grammar\.yml/i)
+
+      if is_shared_definition
+        issues << { type: 'blueprint', message: "High Blast Radius: You are editing a shared blueprint definition. Changes here propagate site-wide to all instances.", severity: 'orange' }
+      end
+
+      if file_path.include?('qss-engine.js')
+        grammar_path = GRAMMAR_PATH
+        if File.exist?(grammar_path)
+          require 'yaml'
+          grammar = YAML.load_file(grammar_path) rescue nil
+          if grammar
+            # Detect manual additions to objectRegistry in JS
+            # blue_names = grammar['objects']&.keys || [] # Placeholder if objects moved to grammar.yml
+            # For now, we enforce that direct JS edits are forbidden.
+            unless raw_content.include?('// GENERATED FROM grammar.yml - DO NOT EDIT')
+              issues << { type: 'protocol', message: "Blueprint Integrity Violation: Manual edits detected in generated engine. Changes must be made in grammar.yml.", severity: 'red' }
+            end
+          end
+        end
+      end
+
+      # Strip ERB tags to avoid parser confusion, but keep placeholders for audit
+      doc_content = raw_content.gsub(/<%.*?%>/m, '<!--ERB-->')
+      doc = Nokogiri::HTML.fragment(doc_content)
+
+      # 1. Global Checks
+      if raw_content.include?('!important')
+        issues << { type: 'protocol', message: "Cheat detected: '!important' is forbidden in QSS", severity: 'red' }
+      end
+
+      # 2. Structural Scoping (Thin Wrapper Protocol)
+      is_thin_protocol_file = raw_content.include?('contain: layout') || raw_content.include?('var(--')
+
+      # 2.0 Shared Definition Overwrite Check (Monkey-patching Prevention)
+      if raw_content.match?(/objectRegistry\s*[\[=]|let\s+objectRegistry|const\s+objectRegistry/i) && !file_path.include?('qss-engine.js')
+        issues << { type: 'protocol', message: "Monkey-patching Violation: Manual override of 'objectRegistry' detected. Object definitions must be registered through registerObject() or config/qss/qss-objects.json.", severity: 'red' }
+      end
+
+      doc.traverse do |node|
+        next unless node.element?
+
+        classes = node['class']&.split(/\s+/) || []
+        styles = node['style'] || ""
+        id = node['id'] || ""
+        is_first_party = first_party?(id, classes, r.id_prefix)
+        is_structural = id.match?(r.structural_id_pattern)
+        active_thin_protocol = is_structural || is_thin_protocol_file
+
+        # A zone is genuinely foreign only if it was established by a non-first-party element
+        is_genuinely_foreign = node.ancestors.any? do |a|
+          a_classes = a['class']&.split(/\s+/) || []
+          a_id = a['id'] || ""
+          a_is_first_party = first_party?(a_id, a_classes, r.id_prefix)
+          (a_classes.include?('foreign') && !a_is_first_party) || a_classes.include?('qss-payload-override')
+        end || (classes.include?('foreign') && !is_first_party) || classes.include?('qss-payload-override')
+
+        # 1.5 Suspicious Foreign Check
+        if is_first_party && classes.include?('foreign')
+          issues << { type: 'protocol', message: "Suspicious Foreign: First-party element <#{node.name}#{id.empty? ? '' : '#' + id}> is using the 'foreign' escape hatch. Verify this is intended.", severity: 'orange' }
+        end
+
+        # 2.1 Inline Styles Check
+        if !styles.empty?
+          # structural check
+          unless is_structural || is_genuinely_foreign
+            issues << { type: 'protocol', message: "Protocol Violation: Inline styles forbidden on non-structural element <#{node.name}#{id.empty? ? '' : '#' + id}>. Use QSS Adjectives.", severity: 'red' }
+          end
+
+          # 2.2 Hardcoded Relational Positioning
+          if active_thin_protocol && !is_genuinely_foreign
+            styles.scan(/\b(?<!-)(left|top|right|bottom|width|height)\s*:\s*(\d+px)/i).each do |prop, val|
+              issues << { type: 'protocol', message: "Thin Wrapper Violation: Hardcoded '#{prop}: #{val}' on ##{id}. Use var() for relational anchoring.", severity: 'red' }
+            end
+          end
+        end
+
+        # 2.3 Containment Enforcement
+        if active_thin_protocol && id.match?(r.narrow_id_pattern)
+          unless styles.include?('contain: layout') || id.include?('portal') || is_genuinely_foreign
+            issues << { type: 'protocol', message: "Thin Wrapper Violation: Structural element ##{id} must carry 'contain: layout'", severity: 'red' }
+          end
+        end
+
+        # 2.4 Stacking Context Warning
+        if active_thin_protocol && prefixed_id?(id, r.id_prefix) && styles.include?('z-index') && !id.include?('portal')
+          z_val = styles.match(/z-index\s*:\s*(\d+)/i)&.captures&.first
+          issues << { type: 'protocol', message: "Stacking Context Warning: z-index:#{z_val} on ##{id} is inside a contained frame. Use #{r.portal_label}.", severity: 'orange' }
+        end
+
+        # 3. Grammar & Payload Checks
+        unless is_genuinely_foreign
+          # 3.1 Payload Positional Violation
+          if PAYLOAD_TAGS.include?(node.name)
+            # Only flag flow-breaking properties. anchored and relative are flow-relative.
+            has_flow_breaking = classes.any? { |c| c.match?(/^(detached|floating|stuck|absolute|pos-x|pos-y|pos-r|pos-b|pos)/) || c.start_with?('^') }
+            if has_flow_breaking && !classes.include?('qss-payload-override')
+              issues << { type: 'protocol', message: "Protocol Violation: Payload tag <#{node.name}> cannot carry flow-breaking adjectives.", severity: 'red' }
+            end
+          end
+
+          # 3.2 DSL Whitelist & Prefix Check
+          classes.each do |cls|
+            # Strip common prefixes for check
+            base_cls = cls.sub(/^(hover|group-hover|focus|active):/, '')
+
+            # Allow recognition of known icon/project-standard prefixes
+            # The consumer's id prefix is NOT allowed as a class prefix (only as an ID prefix)
+            next if r.icon_prefix_pattern && base_cls.match?(r.icon_prefix_pattern)
+
+            # Tailwind-like content allowance (Strictly anchored)
+            next if base_cls.match?(/^(text|bg|border|font|rounded|shadow|opacity|bright)-/)
+            next if base_cls.match?(/\A(m[trblxy]?|p[trblxy]?|w|h|space-[xy]|flex|grid|items|justify|gap|scroll|depth|pos-[xyrb]|text-size|rounded|border)-(\d+|full|auto|hidden|px|f|[\d.]+|ui|overlay|modal|canvas|content|center)\z/)
+            next if base_cls == 'qss'
+
+            unless r.whitelist.include?(base_cls)
+              issues << { type: 'grammar', message: "Foreign Syntax: '#{cls}' is not a valid QSS Adjective", severity: 'red' }
+            end
+          end
+
+          # 3.3 Explicit Dimension Rule
+          if active_thin_protocol && id.match?(r.narrow_id_pattern) && !id.include?('portal')
+            has_width = styles.match(/\bwidth\s*:\s*[^;]+/i) || classes.any? { |c| c.match?(/^(w\[|w-full|w-f|w-\d+)/) || c.match?(/^[A-Z][a-zA-Z0-9]+$/) } || (styles.include?('left:') && styles.include?('right:'))
+            has_height = styles.match(/\bheight\s*:\s*[^;]+/i) || classes.any? { |c| c.match?(/^(h\[|h-full|h-f|h-\d+)/) || c.match?(/^[A-Z][a-zA-Z0-9]+$/) } || (styles.include?('top:') && styles.include?('bottom:'))
+
+            unless (has_width && has_height) || classes.include?('qss-content-driven')
+              issues << { type: 'protocol', message: "Implicit Dimension Warning: Structural element ##{id} lacks explicit dimensions.", severity: 'orange' }
+            end
+          end
+        end
+
+        # 4. Legibility & Ergonomics
+        unless is_genuinely_foreign || classes.include?('qss-legibility-override')
+          classes.each do |cls|
+            if cls.match?(/text-size\[(\d+)\]/)
+              size = cls.match(/text-size\[(\d+)\]/)[1].to_i
+              issues << { type: 'legibility', message: "Font size #{size} below floor (#{LEGIBILITY_FLOOR})", severity: 'orange' } if size < LEGIBILITY_FLOOR
+            end
+          end
+        end
+      end
+
+      status = issues.any? { |i| i[:severity] == 'red' } ? 'red' : (issues.any? { |i| i[:severity] == 'orange' } ? 'orange' : 'green')
+      { status: status, issues: issues }
+    end
+  end
+end