qss 0.2.0 → 0.3.0

data/exe/qss-engine-render-check

@@ -1,86 +1,104 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Renders QSS core's compiled CSS WITH qss-engine.js in headless Chrome and checks engine-only, runtime behavior --
-# the opposite guard from qss-core-render-check, which aborts if the engine is present. Exit 0 when every check
-# passes, 1 otherwise.
-#
-#   qss-engine-render-check [path/to/qss_core.css] [path/to/qss-engine.js]
-
-require "selenium-webdriver"
-require "tmpdir"
-
-css_path = File.expand_path(ARGV[0] || File.join(__dir__, "..", "app", "assets", "stylesheets", "qss", "qss_core.css"))
-js_path = File.expand_path(ARGV[1] || File.join(__dir__, "..", "app", "assets", "javascripts", "qss", "qss-engine.js"))
-abort "qss-engine-render-check: no stylesheet at #{css_path}" unless File.exist?(css_path)
-abort "qss-engine-render-check: no engine at #{js_path}" unless File.exist?(js_path)
-
-HTML = <<~HTML
-  <!doctype html><html><head>
-  <link rel="stylesheet" href="file:///#{css_path.tr('\\', '/')}">
-  <script src="file:///#{js_path.tr('\\', '/')}"></script>
-  </head><body><div id="qss-canvas" style="width: 1000px">
-    <div id="auto-name" class="qss qss-w[200] qss-h[100]"></div>
-    <div id="explicit-name" class="qss qss-w[200] qss-h[100]" style="container-name: custom-name"></div>
-    <div id="no-id-here"></div>
-  </div></body></html>
-HTML
-
-failures = 0
-total = 0
-Dir.mktmpdir do |dir|
-  page = File.join(dir, "qss_engine_render_check.html")
-  File.write(page, HTML)
-  options = Selenium::WebDriver::Chrome::Options.new
-  %w[--headless --disable-gpu --window-size=1400,1000 --allow-file-access-from-files].each { |a| options.add_argument(a) }
-  %w[--no-sandbox --disable-dev-shm-usage].each { |a| options.add_argument(a) } if ENV["CI"]
-  options.binary = ENV["CHROME_BIN"] if ENV["CHROME_BIN"]
-  service = ENV["CHROMEDRIVER_PATH"] ? Selenium::WebDriver::Service.chrome(path: ENV["CHROMEDRIVER_PATH"]) : nil
-  driver = service ? Selenium::WebDriver.for(:chrome, options: options, service: service) : Selenium::WebDriver.for(:chrome, options: options)
-  begin
-    driver.navigate.to("file:///#{page.tr('\\', '/')}")
-    # qss-engine.js declares `const QSSEngine = ...` at top-level script scope: a top-level const/let binding (unlike
-    # var) is never a property of window, so the only reliable presence check is the bare identifier.
-    engine = driver.execute_script("return typeof QSSEngine !== 'undefined'")
-    abort "qss-engine-render-check: qss-engine.js did not load" unless engine
-
-    # The documented usage (README "The JavaScript engine"): startObserver too, not just startPulse -- scanAndTranspile
-    # needs its style tag, which only startObserver creates.
-    driver.execute_script("QSSEngine.setAnchor('#qss-canvas'); QSSEngine.startPulse(); QSSEngine.startObserver();")
-
-    # startPulse's own two nested requestAnimationFrame calls make this genuinely async; poll real elapsed time
-    # (not another assumed frame count) until applyContainerNames has visibly run, or fail outright on timeout.
-    wait = Selenium::WebDriver::Wait.new(timeout: 2)
-    begin
-      wait.until { driver.execute_script("return getComputedStyle(document.getElementById('auto-name')).containerName") != "none" }
-    rescue Selenium::WebDriver::Error::TimeoutError
-      # Let the checks below report the actual (failing) state rather than raising here.
-    end
-
-    computed_name = ->(id) { driver.execute_script("return getComputedStyle(document.getElementById(arguments[0])).containerName", id) }
-
-    [
-      [ "the engine names an actor's container after its own id", "auto-name", "auto-name" ],
-      [ "the engine never overwrites a container-name already set by anything", "explicit-name", "custom-name" ]
-    ].each do |label, id, expected|
-      actual = computed_name.(id)
-      ok = actual == expected
-      total += 1
-      failures += 1 unless ok
-      puts format("%-4s %-56s container-name=%s%s", ok ? "ok" : "FAIL", label, actual, ok ? "" : " (expected #{expected})")
-    end
-
-    # An element with no id at all is never a candidate (nothing to derive a name from) -- confirms the engine
-    # skips it outright rather than, say, setting an empty/undefined name.
-    no_id_name = computed_name.("no-id-here")
-    ok = no_id_name == "none"
-    total += 1
-    failures += 1 unless ok
-    puts format("%-4s %-56s container-name=%s%s", ok ? "ok" : "FAIL", "an id-less element is never named", no_id_name, ok ? "" : " (expected none)")
-  ensure
-    driver.quit
-  end
-end
-
-puts failures.zero? ? "qss-engine-render-check: #{total} of #{total} passed" : "qss-engine-render-check: #{failures} of #{total} FAILED"
-exit(failures.zero? ? 0 : 1)
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Renders QSS core's compiled CSS WITH qss-engine.js in headless Chrome and checks engine-only, runtime behavior --
+# the opposite guard from qss-core-render-check, which aborts if the engine is present. Exit 0 when every check
+# passes, 1 otherwise.
+#
+#   qss-engine-render-check [path/to/qss_core.css] [path/to/qss-engine.js]
+
+require "selenium-webdriver"
+require "tmpdir"
+
+css_path = File.expand_path(ARGV[0] || File.join(__dir__, "..", "app", "assets", "stylesheets", "qss", "qss_core.css"))
+js_path = File.expand_path(ARGV[1] || File.join(__dir__, "..", "app", "assets", "javascripts", "qss", "qss-engine.js"))
+abort "qss-engine-render-check: no stylesheet at #{css_path}" unless File.exist?(css_path)
+abort "qss-engine-render-check: no engine at #{js_path}" unless File.exist?(js_path)
+
+HTML = <<~HTML
+  <!doctype html><html><head>
+  <link rel="stylesheet" href="file:///#{css_path.tr('\\', '/')}">
+  <script src="file:///#{js_path.tr('\\', '/')}"></script>
+  </head><body><div id="qss-canvas" style="width: 1000px">
+    <div id="auto-name" class="qss qss-w[200] qss-h[100]"></div>
+    <div id="explicit-name" class="qss qss-w[200] qss-h[100]" style="container-name: custom-name"></div>
+    <div id="no-id-here"></div>
+    <div id="frame-fixed" class="qss qss-fixed qss-w[200] qss-h[100]"></div>
+    <div id="inner-fixed" style="position: fixed"></div>
+    <div id="inner-sticky" style="position: sticky"></div>
+    <div class="foreign"><div id="foreign-fixed" style="position: fixed"></div></div>
+  </div>
+  <div id="body-fixed" style="position: fixed"></div>
+  <div id="qss-portal"><div id="portal-fixed" style="position: fixed"></div></div>
+  <dialog id="top-layer-modal"></dialog>
+  </body></html>
+HTML
+
+failures = 0
+total = 0
+Dir.mktmpdir do |dir|
+  page = File.join(dir, "qss_engine_render_check.html")
+  File.write(page, HTML)
+  options = Selenium::WebDriver::Chrome::Options.new
+  %w[--headless --disable-gpu --window-size=1400,1000 --allow-file-access-from-files].each { |a| options.add_argument(a) }
+  %w[--no-sandbox --disable-dev-shm-usage].each { |a| options.add_argument(a) } if ENV["CI"]
+  options.binary = ENV["CHROME_BIN"] if ENV["CHROME_BIN"]
+  service = ENV["CHROMEDRIVER_PATH"] ? Selenium::WebDriver::Service.chrome(path: ENV["CHROMEDRIVER_PATH"]) : nil
+  driver = service ? Selenium::WebDriver.for(:chrome, options: options, service: service) : Selenium::WebDriver.for(:chrome, options: options)
+  begin
+    driver.navigate.to("file:///#{page.tr('\\', '/')}")
+    # qss-engine.js declares `const QSSEngine = ...` at top-level script scope: a top-level const/let binding (unlike
+    # var) is never a property of window, so the only reliable presence check is the bare identifier.
+    engine = driver.execute_script("return typeof QSSEngine !== 'undefined'")
+    abort "qss-engine-render-check: qss-engine.js did not load" unless engine
+
+    # The documented usage (README "The JavaScript engine"): startObserver too, not just startPulse -- scanAndTranspile
+    # needs its style tag, which only startObserver creates.
+    driver.execute_script("QSSEngine.setAnchor('#qss-canvas'); QSSEngine.startPulse(); QSSEngine.startObserver();")
+
+    # startPulse's own two nested requestAnimationFrame calls make this genuinely async; poll real elapsed time
+    # (not another assumed frame count) until applyContainerNames has visibly run, or fail outright on timeout.
+    wait = Selenium::WebDriver::Wait.new(timeout: 2)
+    begin
+      wait.until { driver.execute_script("return getComputedStyle(document.getElementById('auto-name')).containerName") != "none" }
+    rescue Selenium::WebDriver::Error::TimeoutError
+      # Let the checks below report the actual (failing) state rather than raising here.
+    end
+
+    computed_name = ->(id) { driver.execute_script("return getComputedStyle(document.getElementById(arguments[0])).containerName", id) }
+
+    [
+      [ "the engine names an actor's container after its own id", "auto-name", "auto-name" ],
+      [ "the engine never overwrites a container-name already set by anything", "explicit-name", "custom-name" ]
+    ].each do |label, id, expected|
+      actual = computed_name.(id)
+      ok = actual == expected
+      total += 1
+      failures += 1 unless ok
+      puts format("%-4s %-56s container-name=%s%s", ok ? "ok" : "FAIL", label, actual, ok ? "" : " (expected #{expected})")
+    end
+
+    # An element with no id at all is never a candidate (nothing to derive a name from) -- confirms the engine
+    # skips it outright rather than, say, setting an empty/undefined name.
+    no_id_name = computed_name.("no-id-here")
+    ok = no_id_name == "none"
+    total += 1
+    failures += 1 unless ok
+    puts format("%-4s %-56s container-name=%s%s", ok ? "ok" : "FAIL", "an id-less element is never named", no_id_name, ok ? "" : " (expected none)")
+
+    # The opt-in positioning diagnostic: fixed/sticky positioning that QSS does not own is reported; a Steel Frame,
+    # the portal, foreign content and a modal <dialog> in the native top layer are not.
+    driver.execute_script("document.getElementById('top-layer-modal').showModal()")
+    flagged = driver.execute_script("return QSSEngine.auditPositioning({ warn: false }).map(o => o.id)").sort
+    expected = %w[body-fixed inner-fixed inner-sticky]
+    ok = flagged == expected
+    total += 1
+    failures += 1 unless ok
+    puts format("%-4s %-56s flagged=%s%s", ok ? "ok" : "FAIL", "auditPositioning reports only non-QSS fixed/sticky", flagged.inspect, ok ? "" : " (expected #{expected.inspect})")
+  ensure
+    driver.quit
+  end
+end
+
+puts failures.zero? ? "qss-engine-render-check: #{total} of #{total} passed" : "qss-engine-render-check: #{failures} of #{total} FAILED"
+exit(failures.zero? ? 0 : 1)

data/exe/qss-sync

@@ -3,6 +3,7 @@
 
 require 'json'
 require 'yaml'
+require_relative '../lib/qss/configuration'
 
 # Generates QSS's derived files from two inputs:
 #   config/grammar.yml      -- core grammar + neutral defaults (source of truth), found relative to this script
@@ -38,6 +39,13 @@ end
 
 config = deep_merge(grammar['config'], consumer['config'] || {})
 
+# The portal root is QSS's own id: "" or "#qss-...". Fail here, before generating anything from a bad value.
+begin
+  [ grammar['config'], config ].each { |c| QSS.validate_portal_root!(c['portal_root']) }
+rescue QSS::ConfigurationError => e
+  abort e.message
+end
+
 # A consumer's grammar_extensions and auditor: settings are NOT written anywhere by this script: the auditors read
 # them at runtime (lib/qss/configuration.rb). Only the consumer's SCSS settings file is generated from them.
 
@@ -161,7 +169,7 @@ def scss_variables(config, header, default)
 end
 
 if CORE_MODE
-  File.write(targets['core_variables'], scss_variables(grammar['config'], 'QSS core defaults, generated from grammar.yml alone', true))
+  File.binwrite(targets['core_variables'], scss_variables(grammar['config'], 'QSS core defaults, generated from grammar.yml alone', true).gsub(/\r?\n/, "\r\n")) # repo files are CRLF
   puts "Generated #{targets['core_variables']}"
 end
 

data/lib/qss/configuration.rb

@@ -3,6 +3,33 @@
 require "yaml"
 
 module QSS
+  # A configuration the gem cannot work with (raised loudly rather than audited around).
+  class ConfigurationError < StandardError; end
+
+  # The overlay portal root is the one element overlays are rooted in, outside the canvas. It is identified by an
+  # exact id, never guessed from substrings or prefixes: config.portal_root, a simple #id selector the project
+  # chooses. Unset, it is `#qss-portal`.
+  DEFAULT_PORTAL_ID = "qss-portal"
+  PORTAL_ROOT_FORMAT = /\A#-?[A-Za-z_][A-Za-z0-9_-]*\z/
+
+  class << self
+    # config.portal_root must be "" (unset) or a simple #id selector.
+    def validate_portal_root!(value)
+      value = value.to_s
+      return value if value.empty? || value.match?(PORTAL_ROOT_FORMAT)
+
+      raise ConfigurationError, "config.portal_root must be a simple #id selector (for example " \
+                                "\"#qss-portal\"), got #{value.inspect}"
+    end
+
+    # Is this id the overlay portal root? Exactly the configured id, or qss-portal when none is configured.
+    def portal_id?(id, portal_root = "")
+      return false if id.to_s.empty?
+
+      id.to_s == (portal_root.to_s.empty? ? DEFAULT_PORTAL_ID : portal_root.to_s.delete_prefix("#"))
+    end
+  end
+
   # 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:
   #
@@ -52,6 +79,7 @@ module QSS
       settings = deep_merge(defaults, data["auditor"] || {})
       portal = data.dig("config", "portal_root")
       settings["portal_root"] = portal.to_s unless portal.nil?
+      QSS.validate_portal_root!(settings["portal_root"])
       settings["registry_path"] = resolve(settings["registry_path"])
       settings["stylesheet_path"] = resolve(settings["stylesheet_path"])
       settings["drywall_stylesheet_path"] = resolve(settings["drywall_stylesheet_path"])

data/lib/qss/qss_auditor.rb

@@ -215,7 +215,7 @@ def self.settings
 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)
+Rules = Struct.new(:id_prefix, :structural_id_pattern, :narrow_id_pattern, :icon_prefix_pattern, :portal_label, :whitelist, :portal_root)
 
 def self.rules(settings = self.settings)
   prefix = settings['id_prefix'].to_s
@@ -227,7 +227,8 @@ def self.rules(settings = self.settings)
     /^#{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
+    extensions.empty? ? DSL_WHITELIST : (DSL_WHITELIST + extensions).uniq,
+    settings['portal_root'].to_s
   )
 end
 
@@ -333,13 +334,13 @@ 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
+          unless styles.include?('contain: layout') || QSS.portal_id?(id, r.portal_root) || 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')
+        if active_thin_protocol && prefixed_id?(id, r.id_prefix) && styles.include?('z-index') && !QSS.portal_id?(id, r.portal_root)
           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
@@ -375,7 +376,7 @@ end
           end
 
           # 3.3 Explicit Dimension Rule
-          if active_thin_protocol && id.match?(r.narrow_id_pattern) && !id.include?('portal')
+          if active_thin_protocol && id.match?(r.narrow_id_pattern) && !QSS.portal_id?(id, r.portal_root)
             has_width = styles.match(/\bwidth\s*:\s*[^;]+/i) || classes.any? { |c| c.match?(/^(qss-w\[|qss-w-full|qss-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?(/^(qss-h\[|qss-h-full|qss-h-f|h-\d+)/) || c.match?(/^[A-Z][a-zA-Z0-9]+$/) } || (styles.include?('top:') && styles.include?('bottom:'))
 

data/lib/qss/qss_native_auditor.rb

@@ -29,16 +29,10 @@ module QSS
       /\b(#{settings['narrow_words'].map { |w| Regexp.escape(w) }.join('|')})\b/i
     end
 
-    # Is this id the overlay portal root? Scoped, not a substring match (an id merely containing "portal" -- a
-    # "portal-nav", a "customer-portal" -- is not an overlay root): the id the project configured as `portal_root`
-    # (a simple #id selector), or `portal` behind the framework prefix (qss-portal, qss-portal-overlays) or the
-    # project's own id prefix (app-portal).
+    # Is this id the overlay portal root? The id configured as `portal_root` (a simple #id selector, see
+    # QSS.validate_portal_root!), or `qss-portal` when none is configured -- exact, never a substring match.
     def self.portal_id?(id, settings = self.settings)
-      return false if id.to_s.empty?
-      configured = settings['portal_root'].to_s
-      return true if configured.match?(/\A#[\w-]+\z/) && id == configured.delete_prefix('#')
-      prefixes = [ 'qss-', id_prefix(settings) ].reject(&:empty?)
-      prefixes.any? { |p| id.match?(/\A#{Regexp.escape(p)}portal(?:-|\z)/) }
+      QSS.portal_id?(id, settings['portal_root'])
     end
 
     def self.portal_label(settings = self.settings)

data/lib/qss/version.rb

@@ -3,7 +3,7 @@
 module QSS
   # The gem's version. QSS::VERSION is the usual spelling; QSS::Version::STRING the same value.
   module Version
-    STRING = "0.2.0"
+    STRING = "0.3.0"
   end
 
   VERSION = Version::STRING

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qss
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kraig Fairhurst
@@ -100,7 +100,7 @@ description: |-
 
   QSS also audits what can be checked statically. Two auditors flag violations such as !important, inline layout styles, undeclared sizes and raw viewport units. RED marks a rule violation and ORANGE a judgment call. Static checks can't prove a page renders, so QSS includes a render check for the compiled CSS alone, and its design history is explicit that only a real browser is real proof.
 
-  QSS was extracted from Parapet, a Rails development tool, which was its first consumer. Its early custom parser was a bug farm, and an invented syntax costs agents more than it buys. Structure moved to plain CSS custom properties; bracket values remain for content such as spacing and sizes. What was tried and dropped is in docs/DESIGN_HISTORY.md.
+  QSS was extracted from a Rails development tool, which was its first consumer. Its early custom parser was a bug farm, and an invented syntax costs agents more than it buys. Structure moved to plain CSS custom properties; bracket values remain for content such as spacing and sizes. What was tried and dropped is in docs/DESIGN_HISTORY.md.
 
   Status: 0.x. Expect names and APIs to change before 1.0.
 email: