@etus/seven-skill 0.1.0-beta.3 → 0.1.0-beta.5

package/cli/engine/detect-antipatterns.mjs

@@ -22,6 +22,7 @@ export {
 } from './registry/seven-antipatterns.mjs'
 export { CHECKS, runChecks } from './rules/checks.mjs'
 export { finding } from './findings.mjs'
+export { allTokenVars, browserTokenProfile, isKnownTokenVar } from './shared/tokens.mjs'
 export { detectText } from './engines/regex/detect-text.mjs'
 export { detectHtml } from './engines/static-html/detect-html.mjs'
 export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.mjs'

package/cli/engine/engines/browser/detect-url.mjs

@@ -7,6 +7,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { finding } from '../../findings.mjs'
+import { browserTokenProfile } from '../../shared/tokens.mjs'
 
 // ─── Browser engine ─────────────────────────────────────────────────────────
 // Live-URL detector. Renders the page with Puppeteer (an optionalDependency),
@@ -46,6 +47,361 @@ function launchArgs() {
   return process.env['CI'] ? ['--no-sandbox', '--disable-setuid-sandbox'] : []
 }
 
+const RUNTIME_RULE_IDS = new Set([
+  'broken-image',
+  'script-error',
+  'content-hidden-at-rest',
+  'edge-flush-cards',
+  'text-occlusion',
+  'heading-rhythm',
+  'text-overflow',
+  'clipped-overflow-container',
+  'design-system-font',
+  'design-system-color',
+  'design-system-radius',
+  'design-system-font-size',
+  'first-viewport-column-overflow',
+  'undersized-ui-text',
+  'repeated-container-text',
+  'gpt-thin-border-wide-shadow',
+])
+
+async function scanRuntimeQuality(page, restrict = null) {
+  const enabled = restrict && restrict.length > 0
+    ? restrict.filter((id) => RUNTIME_RULE_IDS.has(id))
+    : [...RUNTIME_RULE_IDS]
+  if (enabled.length === 0) return []
+
+  return page.evaluate(async ({ enabledRules, tokens }) => {
+    const enabled = new Set(enabledRules)
+    const results = []
+    const seen = new Set()
+    const push = (type, detail) => {
+      if (!enabled.has(type)) return
+      const key = `${type}|${detail}`
+      if (seen.has(key)) return
+      seen.add(key)
+      if (results.filter((item) => item.type === type).length < 20) results.push({ type, detail })
+    }
+    const label = (element) => {
+      if (!element || !element.tagName) return 'element'
+      const id = element.id ? `#${element.id}` : ''
+      const classes = [...element.classList].slice(0, 2).map((name) => `.${name}`).join('')
+      return `${element.tagName.toLowerCase()}${id}${classes}`
+    }
+    const directText = (element) => [...element.childNodes]
+      .filter((node) => node.nodeType === Node.TEXT_NODE)
+      .map((node) => node.textContent || '')
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+    const structurallyVisible = (element, includeTransparent = false) => {
+      for (let current = element; current; current = current.parentElement) {
+        if (current.hidden || current.getAttribute('aria-hidden') === 'true') return false
+        const style = getComputedStyle(current)
+        if (style.display === 'none' || style.visibility === 'collapse') return false
+        if (!includeTransparent && (style.visibility === 'hidden' || Number(style.opacity) <= 0.01)) return false
+      }
+      return true
+    }
+    const waitFrame = () => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+
+    if (enabled.has('content-hidden-at-rest')) {
+      const originalBehavior = document.documentElement.style.scrollBehavior
+      document.documentElement.style.scrollBehavior = 'auto'
+      const maxScroll = Math.max(0, document.documentElement.scrollHeight - innerHeight)
+      const steps = Math.min(16, Math.max(1, Math.ceil(maxScroll / Math.max(innerHeight * 0.8, 400))))
+      for (let index = 0; index <= steps; index++) {
+        scrollTo(0, Math.round((maxScroll * index) / steps))
+        await waitFrame()
+      }
+      scrollTo(0, 0)
+      await waitFrame()
+      document.documentElement.style.scrollBehavior = originalBehavior
+
+      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
+      let totalChars = 0
+      let hiddenChars = 0
+      const samples = []
+      let node
+      while ((node = walker.nextNode())) {
+        const text = (node.textContent || '').replace(/\s+/g, ' ').trim()
+        if (!text || text.length < 2) continue
+        const owner = node.parentElement
+        if (!owner || /^(script|style|noscript|template)$/i.test(owner.tagName)) continue
+        if (!structurallyVisible(owner, true)) continue
+        totalChars += text.length
+        let hidden = false
+        for (let current = owner; current; current = current.parentElement) {
+          const style = getComputedStyle(current)
+          if (style.visibility === 'hidden' || Number(style.opacity) <= 0.01 || style.contentVisibility === 'hidden') {
+            hidden = true
+            break
+          }
+        }
+        if (hidden) {
+          hiddenChars += text.length
+          if (samples.length < 2) samples.push(text.slice(0, 60))
+        }
+      }
+      if (totalChars >= 200 && hiddenChars >= 150 && hiddenChars / totalChars > 0.3) {
+        push('content-hidden-at-rest', `${Math.round((hiddenChars / totalChars) * 100)}% of page text remains hidden after reveal (${hiddenChars}/${totalChars} chars${samples[0] ? `; “${samples[0]}”` : ''})`)
+      }
+    }
+
+    if (enabled.has('broken-image')) {
+      for (const image of document.images) {
+        const source = image.currentSrc || image.getAttribute('src') || ''
+        if (!source || /^(?:#|about:blank)$|(?:placehold|placeholder|example)\./i.test(source) || (image.complete && image.naturalWidth === 0)) {
+          push('broken-image', `${label(image)} has no loadable image source${source ? ` (${source.slice(0, 100)})` : ''}`)
+        }
+      }
+    }
+
+    const elements = [...document.body.querySelectorAll('*')].slice(0, 6000)
+
+    if (enabled.has('text-overflow')) {
+      const skipped = new Set(['PRE', 'CODE', 'TEXTAREA', 'SVG', 'CANVAS', 'SELECT', 'OPTION'])
+      for (const element of elements) {
+        if (skipped.has(element.tagName) || !directText(element) || !structurallyVisible(element)) continue
+        const style = getComputedStyle(element)
+        if (/(auto|scroll)/.test(`${style.overflow} ${style.overflowX}`)) continue
+        let scrollAncestor = false
+        for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+          const parentStyle = getComputedStyle(parent)
+          if (/(auto|scroll)/.test(`${parentStyle.overflow} ${parentStyle.overflowX}`)) {
+            scrollAncestor = true
+            break
+          }
+        }
+        if (scrollAncestor) continue
+        const overflow = element.clientWidth > 0 ? element.scrollWidth - element.clientWidth : 0
+        if (overflow >= 16) push('text-overflow', `${label(element)} overflows its box by ${Math.round(overflow)}px`)
+      }
+    }
+
+    if (enabled.has('clipped-overflow-container')) {
+      for (const container of elements) {
+        const style = getComputedStyle(container)
+        if (!/(hidden|clip)/.test(`${style.overflow} ${style.overflowX} ${style.overflowY}`)) continue
+        const containerRect = container.getBoundingClientRect()
+        if (containerRect.width < 8 || containerRect.height < 8) continue
+        for (const child of container.querySelectorAll('*')) {
+          const childStyle = getComputedStyle(child)
+          if (childStyle.position !== 'absolute') continue
+          if (!directText(child) && child.getAttribute('role') !== 'menu' && !/tooltip|popover|menu/i.test(`${child.className} ${child.getAttribute('data-slot') || ''}`)) continue
+          const childRect = child.getBoundingClientRect()
+          const escapes = childRect.left < containerRect.left - 2 || childRect.right > containerRect.right + 2 || childRect.top < containerRect.top - 2 || childRect.bottom > containerRect.bottom + 2
+          if (escapes) {
+            push('clipped-overflow-container', `${label(container)} clips positioned ${label(child)}`)
+            break
+          }
+        }
+      }
+    }
+
+    if (enabled.has('edge-flush-cards')) {
+      for (const scroller of elements) {
+        const style = getComputedStyle(scroller)
+        if (scroller.scrollWidth <= scroller.clientWidth + 8 || !/(auto|scroll)/.test(`${style.overflowX} ${style.overflow}`)) continue
+        const scrollerRect = scroller.getBoundingClientRect()
+        const children = [...scroller.children].filter((child) => {
+          const rect = child.getBoundingClientRect()
+          return rect.width > 80 && rect.right > scrollerRect.left && rect.left < scrollerRect.right
+        })
+        if (children.length === 0) continue
+        const first = children.sort((left, right) => left.getBoundingClientRect().left - right.getBoundingClientRect().left)[0]
+        const firstRect = first.getBoundingClientRect()
+        const radius = parseFloat(getComputedStyle(first).borderRadius) || 0
+        const inset = firstRect.left - scrollerRect.left
+        if (radius >= 4 && inset >= -2 && inset < 4 && (parseFloat(style.paddingLeft) || 0) < 4) {
+          push('edge-flush-cards', `${label(first)} is flush against the left edge of ${label(scroller)} (${Math.round(inset)}px inset)`)
+        }
+      }
+    }
+
+    if (enabled.has('heading-rhythm')) {
+      for (const heading of document.querySelectorAll('h2,h3,h4,h5,h6')) {
+        if (!structurallyVisible(heading)) continue
+        const previous = heading.previousElementSibling
+        const next = heading.nextElementSibling
+        if (!previous || !next || !structurallyVisible(previous) || !structurallyVisible(next)) continue
+        const headingRect = heading.getBoundingClientRect()
+        const previousRect = previous.getBoundingClientRect()
+        const nextRect = next.getBoundingClientRect()
+        const above = headingRect.top - previousRect.bottom
+        const below = nextRect.top - headingRect.bottom
+        if (above >= -1 && below >= 0 && above <= below + 2) {
+          push('heading-rhythm', `${label(heading)} has ${Math.round(above)}px above and ${Math.round(below)}px below; it reads with the previous block`)
+        }
+      }
+    }
+
+    if (enabled.has('text-occlusion')) {
+      for (const element of elements) {
+        const text = directText(element)
+        if (text.length < 6 || !structurallyVisible(element)) continue
+        const rect = element.getBoundingClientRect()
+        if (rect.width < 20 || rect.height < 10 || rect.bottom < 0 || rect.top > innerHeight) continue
+        const points = [
+          [rect.left + Math.min(6, rect.width / 2), rect.top + rect.height / 2],
+          [rect.left + rect.width / 2, rect.top + rect.height / 2],
+          [rect.right - Math.min(6, rect.width / 2), rect.top + rect.height / 2],
+        ]
+        const blockers = []
+        for (const [x, y] of points) {
+          if (x < 0 || y < 0 || x > innerWidth || y > innerHeight) continue
+          const top = document.elementFromPoint(x, y)
+          if (!top || top === element || element.contains(top) || top.contains(element)) continue
+          const blockerStyle = getComputedStyle(top)
+          const background = blockerStyle.backgroundColor || ''
+          const transparent = background === 'transparent' || /rgba\([^)]*,\s*0(?:\.0+)?\s*\)/.test(background)
+          if (!transparent && Number(blockerStyle.opacity) > 0.5) blockers.push(top)
+        }
+        if (blockers.length >= 2) push('text-occlusion', `${label(element)} text “${text.slice(0, 45)}” is covered by ${label(blockers[0])}`)
+      }
+    }
+
+    if (enabled.has('undersized-ui-text')) {
+      const functional = document.querySelectorAll('a,button,label,th,td,time,option,summary,[role="button"],[role="link"],[role="menuitem"],[role="tab"]')
+      for (const element of functional) {
+        if (!structurallyVisible(element)) continue
+        const identity = `${element.className || ''} ${element.getAttribute('data-slot') || ''}`
+        if (/(?:sr-only|visually-hidden|legal|smallprint|code|terminal)/i.test(identity)) continue
+        const text = directText(element)
+        const size = parseFloat(getComputedStyle(element).fontSize)
+        if (!text || !Number.isFinite(size) || size >= 11 || size <= 0) continue
+        push('undersized-ui-text', `${label(element)} renders functional text at ${size}px: “${text.slice(0, 60)}”`)
+      }
+    }
+
+    if (enabled.has('gpt-thin-border-wide-shadow')) {
+      for (const element of elements) {
+        if (!structurallyVisible(element)) continue
+        const identity = `${element.className || ''} ${element.getAttribute('data-slot') || ''} ${element.getAttribute('role') || ''}`
+        if (/(?:dialog|popover|menu|tooltip|overlay)/i.test(identity)) continue
+        const style = getComputedStyle(element)
+        const borders = [style.borderTopWidth, style.borderRightWidth, style.borderBottomWidth, style.borderLeftWidth]
+          .map((value) => parseFloat(value) || 0)
+          .filter((value) => value > 0)
+        if (borders.length === 0 || Math.max(...borders) > 1.1 || !style.boxShadow || style.boxShadow === 'none') continue
+        const lengths = [...style.boxShadow.matchAll(/(-?[\d.]+)px/g)].map((match) => Math.abs(Number(match[1])))
+        if (lengths.length >= 3 && lengths[2] >= 16) {
+          push('gpt-thin-border-wide-shadow', `${label(element)} combines a ${Math.max(...borders)}px border with ${lengths[2]}px shadow blur`)
+        }
+      }
+    }
+
+    if (enabled.has('repeated-container-text')) {
+      for (const container of elements) {
+        const identity = `${container.className || ''} ${container.getAttribute('data-slot') || ''} ${container.getAttribute('role') || ''}`
+        if (!/(?:card|panel|dialog|sheet|sidebar|region)/i.test(identity) && !/^(ARTICLE|ASIDE)$/.test(container.tagName)) continue
+        const occurrences = new Map()
+        for (const element of container.querySelectorAll('span,p,small,strong,em,label,div')) {
+          const text = directText(element).toLocaleLowerCase('pt-BR')
+          if (text.length < 2 || text.length > 80) continue
+          const structure = `${element.tagName}.${String(element.className || '').split(/\s+/)[0] || ''}`
+          const entry = occurrences.get(text) || []
+          entry.push(structure)
+          occurrences.set(text, entry)
+        }
+        for (const [text, structures] of occurrences) {
+          if (structures.length < 3 || new Set(structures).size < 2) continue
+          push('repeated-container-text', `${label(container)} repeats “${text.slice(0, 60)}” ${structures.length} times`)
+          break
+        }
+      }
+    }
+
+    if (enabled.has('first-viewport-column-overflow')) {
+      const candidates = elements.filter((element) => {
+        if (!structurallyVisible(element)) return false
+        const rect = element.getBoundingClientRect()
+        if (rect.top < -20 || rect.top > innerHeight * 0.8 || rect.width < Math.min(640, innerWidth * 0.7)) return false
+        const style = getComputedStyle(element)
+        return style.display === 'grid' || style.display === 'flex'
+      })
+      for (const container of candidates) {
+        const children = [...container.children]
+          .map((element) => ({ element, rect: element.getBoundingClientRect() }))
+          .filter(({ rect }) => rect.width >= 180 && rect.height >= 80 && rect.top < innerHeight)
+        if (children.length < 2) continue
+        const row = children.filter(({ rect }) => Math.abs(rect.top - children[0].rect.top) <= 80)
+        if (row.length < 2) continue
+        const heights = row.map(({ rect }) => rect.height).sort((a, b) => a - b)
+        const shortest = heights[0]
+        const tallest = heights[heights.length - 1]
+        if (shortest <= innerHeight * 1.1 && tallest >= innerHeight * 1.5 && tallest - shortest >= innerHeight * 0.75) {
+          push('first-viewport-column-overflow', `${label(container)} opening columns are ${Math.round(shortest)}px and ${Math.round(tallest)}px tall in a ${innerHeight}px viewport`)
+        }
+      }
+    }
+
+    const profileRules = ['design-system-font', 'design-system-color', 'design-system-radius', 'design-system-font-size']
+    if (profileRules.some((rule) => enabled.has(rule))) {
+      const fonts = new Set(tokens.fontFamilies.map((font) => font.toLowerCase()))
+      const fontSizes = tokens.fontSizesPx
+      const radii = tokens.radiiPx
+      const closeTo = (value, values, tolerance = 0.2) => values.some((allowed) => Math.abs(value - allowed) <= tolerance)
+      const normalizedColor = (value) => String(value || '').toLowerCase().replace(/\s+/g, '')
+      const allowedColors = new Set()
+      if (enabled.has('design-system-color')) {
+        const probe = document.createElement('span')
+        probe.hidden = true
+        document.body.appendChild(probe)
+        for (const variable of tokens.colorVars) {
+          probe.style.color = 'rgb(1, 2, 3)'
+          probe.style.color = `var(${variable}, rgb(1, 2, 3))`
+          const resolved = normalizedColor(getComputedStyle(probe).color)
+          if (resolved && resolved !== 'rgb(1,2,3)') allowedColors.add(resolved)
+        }
+        probe.remove()
+      }
+      const reported = { font: new Set(), color: new Set(), radius: new Set(), size: new Set() }
+      for (const element of elements) {
+        if (!structurallyVisible(element)) continue
+        const style = getComputedStyle(element)
+        const text = directText(element)
+        if (enabled.has('design-system-font') && text) {
+          const primary = (style.fontFamily.split(',')[0] || '').replace(/["']/g, '').trim().toLowerCase()
+          if (primary && !fonts.has(primary) && !reported.font.has(primary)) {
+            reported.font.add(primary)
+            push('design-system-font', `${label(element)} uses ${primary}; allowed: ${[...fonts].join(', ')}`)
+          }
+        }
+        if (enabled.has('design-system-font-size') && text) {
+          const size = parseFloat(style.fontSize)
+          if (Number.isFinite(size) && !closeTo(size, fontSizes) && !reported.size.has(size)) {
+            reported.size.add(size)
+            push('design-system-font-size', `${label(element)} renders at ${size}px, outside the Seven type ramp`)
+          }
+        }
+        if (enabled.has('design-system-radius')) {
+          const radius = parseFloat(style.borderTopLeftRadius)
+          if (radius > 0 && !closeTo(radius, radii) && !reported.radius.has(radius)) {
+            reported.radius.add(radius)
+            push('design-system-radius', `${label(element)} renders with ${radius}px radius, outside the Seven scale`)
+          }
+        }
+        if (enabled.has('design-system-color') && allowedColors.size > 0) {
+          const candidates = []
+          if (text) candidates.push(['text', style.color])
+          if (style.backgroundColor && !/^(?:transparent|rgba\([^)]*,\s*0(?:\.0+)?\s*\))$/i.test(style.backgroundColor)) candidates.push(['background', style.backgroundColor])
+          for (const [kind, raw] of candidates) {
+            const color = normalizedColor(raw)
+            const key = `${kind}:${color}`
+            if (!color || allowedColors.has(color) || reported.color.has(key)) continue
+            reported.color.add(key)
+            push('design-system-color', `${label(element)} ${kind} resolves to ${raw}, outside the active Seven token palette`)
+          }
+        }
+      }
+    }
+
+    return results
+  }, { enabledRules: enabled, tokens: browserTokenProfile() })
+}
+
 /**
  * Scan one already-loaded page: inject the bundle, run the in-browser
  * detector, normalize the findings. Shared by the one-shot and reusable paths.
@@ -58,7 +414,9 @@ async function scanPage(page, url, browserBundle, options = {}) {
     return window.sevenDetect()
   })
   const restrict = ruleIds || only
-  let findings = raw.map((f) => finding(f.type, url, f.detail))
+  const runtime = await scanRuntimeQuality(page, restrict)
+  const pageErrors = (options.pageErrors || []).slice(0, 5).map((detail) => ({ type: 'script-error', detail }))
+  let findings = [...raw, ...runtime, ...pageErrors].map((f) => finding(f.type, url, f.detail))
   if (restrict && restrict.length > 0) {
     findings = findings.filter((f) => restrict.includes(f.antipattern))
   }
@@ -78,10 +436,15 @@ export async function createBrowserDetector(options = {}) {
     browser,
     async detectUrl(url, scanOptions = {}) {
       const page = await browser.newPage()
+      const pageErrors = []
+      page.on('pageerror', (error) => {
+        const message = String(error?.message || error).split('\n')[0].trim().slice(0, 200)
+        if (message && !pageErrors.includes(message)) pageErrors.push(message)
+      })
       try {
         await page.setViewport(viewport)
-        await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 })
-        return await scanPage(page, url, browserBundle, scanOptions)
+        await page.goto(url, { waitUntil: scanOptions.waitUntil || options.waitUntil || 'networkidle2', timeout: 30000 })
+        return await scanPage(page, url, browserBundle, { ...scanOptions, pageErrors })
       } finally {
         await page.close().catch(() => {})
       }