@etus/seven-skill 0.1.0-beta.1

package/cli/engine/shared/color.mjs

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+// ─── Color utilities ────────────────────────────────────────────────────────
+
+export function isNeutralColor(color) {
+  if (!color || color === 'transparent') return true
+
+  // rgb/rgba — channel spread. Threshold 30 is ~11.7% of the 0-255 range.
+  const rgb = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/)
+  if (rgb) {
+    return Math.max(+rgb[1], +rgb[2], +rgb[3]) - Math.min(+rgb[1], +rgb[2], +rgb[3]) < 30
+  }
+
+  // oklch()/lch() — chroma is the second numeric component. Seven's tokens are
+  // OKLCH throughout, so this path matters: chroma >= 0.02 reads as tinted.
+  const oklch = color.match(/oklch\(\s*[\d.]+%?\s*([\d.-]+)/i)
+  if (oklch) return parseFloat(oklch[1]) < 0.02
+  const lch = color.match(/lch\(\s*[\d.]+%?\s*([\d.-]+)/i)
+  if (lch) return parseFloat(lch[1]) < 3
+
+  // oklab()/lab() — a and b are signed axes; chroma = hypot(a, b).
+  const oklab = color.match(/oklab\(\s*[\d.]+%?\s*([\d.-]+)\s+([\d.-]+)/i)
+  if (oklab) return Math.hypot(parseFloat(oklab[1]), parseFloat(oklab[2])) < 0.02
+  const lab = color.match(/lab\(\s*[\d.]+%?\s*([\d.-]+)\s+([\d.-]+)/i)
+  if (lab) return Math.hypot(parseFloat(lab[1]), parseFloat(lab[2])) < 3
+
+  // hsl/hsla — saturation is the second numeric component (percent).
+  const hsl = color.match(/hsla?\(\s*[\d.-]+\s*,?\s*([\d.]+)%/i)
+  if (hsl) return parseFloat(hsl[1]) < 10
+
+  // hwb(hue whiteness% blackness%) — gray when whiteness + blackness >= 100.
+  const hwb = color.match(/hwb\(\s*[\d.-]+\s+([\d.]+)%\s+([\d.]+)%/i)
+  if (hwb) {
+    const w = parseFloat(hwb[1])
+    const b = parseFloat(hwb[2])
+    return 1 - Math.min(100, w + b) / 100 < 0.1
+  }
+
+  // Unknown format — err on the side of DETECTING rather than skipping.
+  return false
+}
+
+export function parseRgb(color) {
+  if (!color || color === 'transparent') return null
+  const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/)
+  if (!m) return null
+  return { r: +m[1], g: +m[2], b: +m[3], a: m[4] === undefined ? 1 : +m[4] }
+}
+
+export function parseHex(hex) {
+  if (!hex) return null
+  const m = hex.match(/^#([0-9a-f]{3,8})$/i)
+  if (!m) return null
+  const h = m[1]
+  if (h.length === 3) {
+    return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16), a: 1 }
+  }
+  if (h.length === 6 || h.length === 8) {
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+      a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
+    }
+  }
+  return null
+}
+
+export function relativeLuminance({ r, g, b }) {
+  const [rs, gs, bs] = [r / 255, g / 255, b / 255].map((c) =>
+    c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+  )
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs
+}
+
+export function contrastRatio(c1, c2) {
+  const l1 = relativeLuminance(c1)
+  const l2 = relativeLuminance(c2)
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)
+}
+
+export function hasChroma(c, threshold = 30) {
+  if (!c) return false
+  return Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b) >= threshold
+}
+
+export function getHue(c) {
+  if (!c) return 0
+  const r = c.r / 255
+  const g = c.g / 255
+  const b = c.b / 255
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  if (max === min) return 0
+  const d = max - min
+  let h
+  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6
+  else if (max === g) h = ((b - r) / d + 2) / 6
+  else h = ((r - g) / d + 4) / 6
+  return Math.round(h * 360)
+}
+
+export function colorToHex(c) {
+  if (!c) return '?'
+  return '#' + [c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * Fuchsia / magenta detection. Seven reserves fuchsia for charts; on UI chrome
+ * it is an anti-pattern. A color is "fuchsia" when it has real chroma and its
+ * hue sits in the magenta band (roughly 280-340 degrees).
+ */
+export function isFuchsia(c) {
+  if (!c || !hasChroma(c, 40)) return false
+  const hue = getHue(c)
+  return hue >= 280 && hue <= 340
+}
+
+/**
+ * OKLCH -> sRGB. Seven's color tokens are OKLCH; matching them to hex/rgb
+ * literals in code needs this conversion. Follows the CSS Color 4 / Björn
+ * Ottosson reference. L is 0-1, C is chroma, H is degrees.
+ */
+export function oklchToRgb(L, C, H) {
+  const hRad = (H * Math.PI) / 180
+  const a = C * Math.cos(hRad)
+  const b = C * Math.sin(hRad)
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b
+  const l = l_ ** 3
+  const m = m_ ** 3
+  const s = s_ ** 3
+  const lr = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s
+  const lg = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s
+  const lb = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s
+  const gamma = (x) => (x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055)
+  return [gamma(lr), gamma(lg), gamma(lb)].map((v) => Math.round(Math.max(0, Math.min(1, v)) * 255))
+}
+
+/** Canonical form for an exact-string token match: trimmed, lowercased,
+ *  whitespace-collapsed. Shared by the token-data build step and the runtime
+ *  accessor. */
+export function normalizeRaw(value) {
+  return String(value).trim().toLowerCase().replace(/\s+/g, ' ')
+}
+
+/**
+ * Reduce any color literal (oklch, hex, rgb/rgba) to a canonical `r,g,b,a`
+ * key. Shared by the token-data build step and the runtime token accessor so
+ * a literal in consumer code matches a Seven token regardless of format.
+ * Returns null when the value is not a recognized color.
+ */
+export function colorToRgbaKey(value) {
+  if (!value || typeof value !== 'string') return null
+  const v = value.trim().toLowerCase()
+
+  const oklch = v.match(/oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+)(%?))?\s*\)/)
+  if (oklch) {
+    const L = oklch[2] === '%' ? parseFloat(oklch[1]) / 100 : parseFloat(oklch[1])
+    const C = parseFloat(oklch[3])
+    const H = parseFloat(oklch[4])
+    let alpha = 1
+    if (oklch[5] !== undefined) {
+      alpha = oklch[6] === '%' ? parseFloat(oklch[5]) / 100 : parseFloat(oklch[5])
+    }
+    const [r, g, b] = oklchToRgb(L, C, H)
+    return `${r},${g},${b},${alpha.toFixed(2)}`
+  }
+
+  const hex = v.match(/^#([0-9a-f]{3,8})$/)
+  if (hex) {
+    const h = hex[1]
+    let r
+    let g
+    let b
+    let a = 1
+    if (h.length === 3 || h.length === 4) {
+      r = parseInt(h[0] + h[0], 16)
+      g = parseInt(h[1] + h[1], 16)
+      b = parseInt(h[2] + h[2], 16)
+      if (h.length === 4) a = parseInt(h[3] + h[3], 16) / 255
+    } else if (h.length === 6 || h.length === 8) {
+      r = parseInt(h.slice(0, 2), 16)
+      g = parseInt(h.slice(2, 4), 16)
+      b = parseInt(h.slice(4, 6), 16)
+      if (h.length === 8) a = parseInt(h.slice(6, 8), 16) / 255
+    } else {
+      return null
+    }
+    return `${r},${g},${b},${a.toFixed(2)}`
+  }
+
+  const rgb = v.match(/rgba?\(\s*(\d+)\s*[, ]\s*(\d+)\s*[, ]\s*(\d+)\s*(?:[,/]\s*([\d.]+)(%?))?\s*\)/)
+  if (rgb) {
+    let a = 1
+    if (rgb[4] !== undefined) a = rgb[5] === '%' ? parseFloat(rgb[4]) / 100 : parseFloat(rgb[4])
+    return `${+rgb[1]},${+rgb[2]},${+rgb[3]},${a.toFixed(2)}`
+  }
+
+  return null
+}

package/cli/engine/shared/constants.mjs

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+// ─── Seven-specific catalogs ────────────────────────────────────────────────
+
+/**
+ * The only sans face allowed in Seven. Note this INVERTS impeccable's
+ * `OVERUSED_FONTS` rule: impeccable flags Inter as overused, Seven mandates it.
+ */
+export const INTER_FAMILY_NAMES = new Set([
+  'inter',
+  'inter-variable',
+  'intervariable',
+  'inter var',
+])
+
+/** The only mono face allowed in Seven. */
+export const JETBRAINS_MONO_FAMILY_NAMES = new Set([
+  'jetbrains mono',
+  'jetbrains-mono',
+  'jetbrainsmono',
+])
+
+/** Generic / system fallbacks that never count as a non-Inter face. */
+export const SYSTEM_FONT_FALLBACK_TOKENS = new Set([
+  'system-ui',
+  '-apple-system',
+  'blinkmacsystemfont',
+  'segoe ui',
+  'roboto',
+  'helvetica',
+  'helvetica neue',
+  'arial',
+  'sans-serif',
+  'serif',
+  'monospace',
+  'ui-monospace',
+  'ui-sans-serif',
+  'ui-serif',
+  'ui-rounded',
+  'menlo',
+  'consolas',
+  'courier new',
+  'inherit',
+  'initial',
+  'unset',
+  'revert',
+])
+
+/** HTML tags whose own styling never trips element-level rules. */
+export const SAFE_TAGS = new Set([
+  'html', 'head', 'body', 'script', 'style', 'link', 'meta', 'title', 'br',
+  'svg', 'path', 'circle', 'rect', 'line', 'polyline', 'polygon', 'g', 'defs', 'use',
+])
+
+/** European Portuguese vocabulary that must not appear in pt-BR chrome. */
+export const PT_PT_VOCAB_PAIRS = [
+  { ptPt: 'ficheiro', ptBr: 'arquivo' },
+  { ptPt: 'ficheiros', ptBr: 'arquivos' },
+  { ptPt: 'telemóvel', ptBr: 'celular' },
+  { ptPt: 'telemóveis', ptBr: 'celulares' },
+  { ptPt: 'ecrã', ptBr: 'tela' },
+  { ptPt: 'ecrãs', ptBr: 'telas' },
+  { ptPt: 'rato', ptBr: 'mouse' },
+  { ptPt: 'autocarro', ptBr: 'ônibus' },
+  { ptPt: 'gestor', ptBr: 'gerente' },
+  { ptPt: 'utilizador', ptBr: 'usuário' },
+  { ptPt: 'utilizadores', ptBr: 'usuários' },
+  { ptPt: 'sítio', ptBr: 'site' },
+  { ptPt: 'apagar', ptBr: 'excluir' },
+]
+
+/**
+ * Package names whose source is exempt from rules that would mis-fire on
+ * token-defining or skill-defining code. Resolved by walking up to the
+ * nearest package.json — works inside the monorepo and inside a consumer's
+ * node_modules alike.
+ */
+export const SEVEN_INTERNAL_PACKAGES = new Set(['@etus/ui', '@etus/tokens', '@etus/seven-skill'])
+
+/** Path segments whose files define tokens and may carry raw color literals. */
+export const TOKEN_DEFINITION_PATH_SEGMENTS = [
+  'packages/tokens/sources/',
+  'packages/tokens/sd/',
+  'packages/tokens/dist/',
+  'docs/tokens-json/',
+]
+
+/** Test fixtures are always scanned regardless of the package they sit in. */
+export const FIXTURES_PATH_SEGMENT = '/tests/fixtures/'

package/cli/engine/shared/page.mjs

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+/** True when the content looks like a full HTML page, not a component partial. */
+export function isFullPage(content) {
+  const stripped = content.replace(/<!--[\s\S]*?-->/g, '')
+  return /<!doctype\s|<html[\s>]|<head[\s>]/i.test(stripped)
+}

package/cli/engine/shared/tokens.mjs

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+/*
+ * Token accessor. The single API the rule layer uses to consult Seven's
+ * design tokens. It wraps the build-time snapshot (token-data.generated.mjs,
+ * derived from @etus/tokens) behind semantic accessors so the rules never see
+ * the snapshot's raw shape — the snapshot can change without touching a rule.
+ */
+
+import { TOKEN_DATA } from '../token-data.generated.mjs'
+import { colorToRgbaKey, normalizeRaw } from './color.mjs'
+
+/** True when the snapshot carries usable data. Rules fall back to heuristics
+ *  if this is ever false (defensive — not expected in a built package). */
+export function tokenDataAvailable() {
+  return Boolean(TOKEN_DATA && Object.keys(TOKEN_DATA.colorByRgba || {}).length > 0)
+}
+
+// ─── Color ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a literal color (hex, rgb, oklch) to the Seven token cssVar that
+ * declares it, or null when no token matches. Format-insensitive: a hex
+ * literal resolves the same OKLCH token as the OKLCH form.
+ */
+export function colorToCssVar(rawValue) {
+  if (!rawValue) return null
+  const key = colorToRgbaKey(rawValue)
+  if (key && TOKEN_DATA.colorByRgba[key]) return TOKEN_DATA.colorByRgba[key]
+  const raw = normalizeRaw(rawValue)
+  return TOKEN_DATA.colorByRaw[raw] || null
+}
+
+/** True when the literal color is a declared Seven token value. */
+export function isKnownTokenColor(rawValue) {
+  return colorToCssVar(rawValue) !== null
+}
+
+// ─── Typography ─────────────────────────────────────────────────────────────
+
+/**
+ * The sans/mono families Seven sanctions. Derived from the `fontFamily`
+ * tokens, plus JetBrains Mono — Seven's documented code face, which the
+ * current token catalog does not yet declare as a `fontFamily` token.
+ */
+export function allowedFontFamilies() {
+  return [...new Set([...TOKEN_DATA.fontFamilies, 'jetbrains mono'])]
+}
+
+export function isAllowedFontFamily(name) {
+  if (!name) return false
+  return allowedFontFamilies().includes(String(name).trim().toLowerCase())
+}
+
+export function fontSizesPx() {
+  return TOKEN_DATA.fontSizesPx
+}
+
+/** The smallest declared font size — the floor `tiny-text` enforces. */
+export function minFontSizePx() {
+  return TOKEN_DATA.fontSizesPx.length > 0 ? TOKEN_DATA.fontSizesPx[0] : 12
+}
+
+export function lineHeights() {
+  return TOKEN_DATA.lineHeights
+}
+
+export function letterSpacings() {
+  return TOKEN_DATA.letterSpacings
+}
+
+// ─── Shape ──────────────────────────────────────────────────────────────────
+
+export function radiusScale() {
+  return TOKEN_DATA.radii
+}
+
+export function componentRadiiPx() {
+  return TOKEN_DATA.radii.component
+}
+
+export function surfaceRadiiPx() {
+  return TOKEN_DATA.radii.surface
+}
+
+export function pillRadiiPx() {
+  return TOKEN_DATA.radii.pill
+}
+
+export function spacingScalePx() {
+  return TOKEN_DATA.spacingPx
+}
+
+// ─── Motion ─────────────────────────────────────────────────────────────────
+
+/** Motion duration tokens as `{ cssVar: value }`. */
+export function motionDurations() {
+  return TOKEN_DATA.durations
+}
+
+/** Easing tokens as `{ cssVar: cubic-bezier-value }`. Includes `--ease-bounce`
+ *  and `--ease-spring` — Seven's catalog does declare them, so a bounce easing
+ *  is drift only when it is NOT one of these sanctioned tokens. */
+export function easingTokens() {
+  return TOKEN_DATA.easings
+}
+
+/** The set of sanctioned cubic-bezier values, normalized for comparison. */
+export function sanctionedEasingValues() {
+  return new Set(Object.values(TOKEN_DATA.easings).map((v) => normalizeRaw(v)))
+}
+
+/** Sanctioned easing tokens parsed to [x1, y1, x2, y2] tuples. A cubic-bezier
+ *  in code that matches one of these is a Seven easing token value, not drift —
+ *  even when its curve overshoots (the catalog declares --ease-bounce). */
+export function sanctionedEasingBeziers() {
+  const out = []
+  for (const value of Object.values(TOKEN_DATA.easings)) {
+    const m = String(value).match(
+      /cubic-bezier\(\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\)/
+    )
+    if (m) out.push([+m[1], +m[2], +m[3], +m[4]])
+  }
+  return out
+}
+
+// ─── Elevation ──────────────────────────────────────────────────────────────
+
+export function shadowTokens() {
+  return TOKEN_DATA.shadows
+}
+
+// ─── Semantic roles ─────────────────────────────────────────────────────────
+
+/**
+ * The Seven semantic-color token for a role (success, destructive, warning,
+ * info, muted, accent, ...). Prefers a fill/background variant, then the bare
+ * role token. Returns null when no semantic token carries that role — used to
+ * point a Tailwind palette utility at its Seven equivalent.
+ */
+export function suggestSemanticToken(role) {
+  const vars = TOKEN_DATA.semanticColorVars || []
+  const matches = vars.filter((v) => v.includes(role))
+  if (matches.length === 0) return null
+  return (
+    matches.find((v) => v.endsWith('-background')) ||
+    matches.find((v) => v === `--${role}`) ||
+    matches.find((v) => !v.includes('-foreground') && !v.includes('-border')) ||
+    matches[0]
+  )
+}