@lugom.io/hefesto 0.2.0 → 0.3.0

package/skills/hefesto-design/scripts/audit.py

@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""Scanner de violações do contrato de design para o Hefesto.
+
+Varre código-fonte contra o DESIGN.md e reporta cores não autorizadas,
+fontes não contratadas, espaçamentos fora da escala e CTAs genéricos.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+
+SCANNABLE_EXTENSIONS = {
+    ".tsx", ".jsx", ".vue", ".svelte", ".css", ".scss",
+    ".html", ".astro", ".ts", ".js",
+}
+
+GENERIC_CTAS = {
+    "submit", "click here", "clique aqui", "ok", "cancel", "cancelar",
+    "send", "enviar", "close", "fechar", "yes", "sim", "no", "não",
+    "next", "próximo", "proximo", "previous", "anterior", "back", "voltar",
+    "continue", "continuar", "accept", "aceitar", "confirm", "confirmar",
+    "delete", "deletar", "remove", "remover", "save", "salvar",
+}
+
+
+def _is_binary(filepath):
+    """Verifica se o arquivo parece ser binário."""
+    try:
+        with open(filepath, "rb") as f:
+            chunk = f.read(1024)
+        return b"\x00" in chunk
+    except (IOError, OSError):
+        return True
+
+
+def parse_design_md(design_path):
+    """Extrai contratos do DESIGN.md.
+
+    Retorna dict com:
+        colors: set de cores hex normalizadas (lowercase)
+        fonts: set de nomes de fonte (lowercase)
+        spacing_base: int (unidade base de espaçamento, padrão 4)
+        cta_texts: set de textos de CTA aprovados (lowercase)
+    """
+    try:
+        with open(design_path, "r", encoding="utf-8") as f:
+            content = f.read()
+    except FileNotFoundError:
+        print(f"Erro: arquivo não encontrado: {design_path}", file=sys.stderr)
+        sys.exit(1)
+
+    contract = {
+        "colors": set(),
+        "fonts": set(),
+        "spacing_base": 4,
+        "cta_texts": set(),
+    }
+
+    sections = _split_sections(content)
+
+    # Cores
+    colors_text = sections.get("contrato de cores", "")
+    for match in re.finditer(r"#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b", colors_text):
+        contract["colors"].add(match.group(0).lower())
+
+    # Tipografia
+    typo_text = sections.get("contrato de tipografia", "")
+    for match in re.finditer(r"font-family[:\s]*[\"']?([^\"';,\n]+)", typo_text, re.IGNORECASE):
+        contract["fonts"].add(match.group(1).strip().lower())
+    # Também captura nomes entre aspas ou backticks
+    for match in re.finditer(r"[`\"']([A-Z][a-zA-Z\s]+(?:Sans|Serif|Mono|Display|Text)?)[`\"']", typo_text):
+        contract["fonts"].add(match.group(1).strip().lower())
+
+    # Espaçamento
+    spacing_text = sections.get("contrato de espacamento", sections.get("contrato de espaçamento", ""))
+    base_match = re.search(r"base[:\s]*(\d+)", spacing_text, re.IGNORECASE)
+    if base_match:
+        contract["spacing_base"] = int(base_match.group(1))
+
+    # Copywriting
+    copy_text = sections.get("copywriting", "")
+    for match in re.finditer(r"[`\"']([^`\"']+)[`\"']", copy_text):
+        contract["cta_texts"].add(match.group(1).strip().lower())
+
+    return contract
+
+
+def _split_sections(content):
+    """Divide conteúdo markdown em seções por heading."""
+    sections = {}
+    current_key = ""
+    current_lines = []
+
+    for line in content.split("\n"):
+        heading_match = re.match(r"^#{1,4}\s+(.+)", line)
+        if heading_match:
+            if current_key:
+                sections[current_key] = "\n".join(current_lines)
+            raw_key = heading_match.group(1).strip().lower()
+            # Normaliza removendo acentos simples para matching
+            current_key = raw_key.replace("ã", "a").replace("é", "e").replace("ç", "c").replace("á", "a").replace("ó", "o").replace("ú", "u")
+            current_lines = []
+        else:
+            current_lines.append(line)
+
+    if current_key:
+        sections[current_key] = "\n".join(current_lines)
+
+    return sections
+
+
+def scan_colors(filepath, lines, contract_colors):
+    """Encontra cores hex não contratadas."""
+    violations = []
+    hex_pattern = re.compile(r"#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b")
+
+    var_pattern = re.compile(r"var\([^)]*\)")
+
+    for lineno, line in enumerate(lines, 1):
+        # Build set of positions covered by var() expressions to skip
+        var_spans = set()
+        for vm in var_pattern.finditer(line):
+            for pos in range(vm.start(), vm.end()):
+                var_spans.add(pos)
+
+        for match in hex_pattern.finditer(line):
+            # Skip hex colors inside var() — e.g., var(--color, #abc123)
+            if match.start() in var_spans:
+                continue
+            found = match.group(0).lower()
+            # Normaliza #RGB para #RRGGBB para comparação
+            if len(found) == 4:
+                expanded = "#" + "".join(c * 2 for c in found[1:])
+                if expanded not in contract_colors and found not in contract_colors:
+                    violations.append({
+                        "file": filepath,
+                        "line": lineno,
+                        "type": "color",
+                        "found": found,
+                        "suggestion": "Use uma cor do contrato de cores do DESIGN.md",
+                    })
+            elif found not in contract_colors:
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "color",
+                    "found": found,
+                    "suggestion": "Use uma cor do contrato de cores do DESIGN.md",
+                })
+
+    return violations
+
+
+def scan_typography(filepath, lines, contract_fonts):
+    """Encontra font-family não contratadas."""
+    violations = []
+    font_pattern = re.compile(r"font-family\s*:\s*([^;}\n]+)", re.IGNORECASE)
+    font_js_pattern = re.compile(r"fontFamily\s*:\s*['\"]([^'\"]+)['\"]")
+
+    for lineno, line in enumerate(lines, 1):
+        # CSS-in-JS: fontFamily: "Inter" / fontFamily: 'Inter'
+        for match in font_js_pattern.finditer(line):
+            font_name = match.group(1).strip()
+            normalized = font_name.lower()
+            if normalized not in {"serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "inherit", "initial", "unset"}:
+                if normalized not in contract_fonts:
+                    violations.append({
+                        "file": filepath,
+                        "line": lineno,
+                        "type": "typography",
+                        "found": font_name,
+                        "suggestion": f"Use uma fonte do contrato: {', '.join(contract_fonts) or '(nenhuma definida)'}",
+                    })
+
+        for match in font_pattern.finditer(line):
+            fonts_str = match.group(1)
+            # Extrai nomes de fontes individuais
+            font_names = re.findall(r"[\"']?([a-zA-Z][a-zA-Z\s-]+)[\"']?", fonts_str)
+            for font_name in font_names:
+                normalized = font_name.strip().lower()
+                # Ignora fontes genéricas CSS
+                if normalized in {"serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "inherit", "initial", "unset"}:
+                    continue
+                if normalized not in contract_fonts:
+                    violations.append({
+                        "file": filepath,
+                        "line": lineno,
+                        "type": "typography",
+                        "found": font_name.strip(),
+                        "suggestion": f"Use uma fonte do contrato: {', '.join(contract_fonts) or '(nenhuma definida)'}",
+                    })
+
+    return violations
+
+
+def scan_spacing(filepath, lines, base_unit):
+    """Encontra valores de espaçamento que não são múltiplos da unidade base."""
+    violations = []
+    # CSS inline: padding: 13px, margin: 7px 5px, gap: 9px
+    spacing_pattern = re.compile(
+        r"(?:padding|margin|gap|top|right|bottom|left)\s*:\s*(\d+)\s*px",
+        re.IGNORECASE,
+    )
+    # CSS shorthand: padding: 10px 15px (captures each value)
+    spacing_shorthand = re.compile(
+        r"(?:padding|margin)\s*:\s*((?:\d+px\s*)+)",
+        re.IGNORECASE,
+    )
+    # CSS-in-JS: padding: 13, margin: 7 (numeric values without px)
+    spacing_js_pattern = re.compile(
+        r"(?:padding|margin|gap|top|right|bottom|left)\s*:\s*(\d+)\s*[,}\n]",
+    )
+    # Tailwind: p-3, m-5, gap-7 (scale * 4 = px)
+    tailwind_pattern = re.compile(r"\b(?:p|m|gap)-(\d+)\b")
+
+    for lineno, line in enumerate(lines, 1):
+        checked_values = set()
+
+        for match in spacing_pattern.finditer(line):
+            value = int(match.group(1))
+            if value > 0 and value % base_unit != 0 and value not in checked_values:
+                checked_values.add(value)
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "spacing",
+                    "found": f"{value}px",
+                    "suggestion": f"Use múltiplo de {base_unit}px (ex: {(value // base_unit) * base_unit}px ou {((value // base_unit) + 1) * base_unit}px)",
+                })
+
+        # CSS shorthand: extract each px value
+        for match in spacing_shorthand.finditer(line):
+            for val_match in re.finditer(r"(\d+)px", match.group(1)):
+                value = int(val_match.group(1))
+                if value > 0 and value % base_unit != 0 and value not in checked_values:
+                    checked_values.add(value)
+                    violations.append({
+                        "file": filepath,
+                        "line": lineno,
+                        "type": "spacing",
+                        "found": f"{value}px",
+                        "suggestion": f"Use múltiplo de {base_unit}px (ex: {(value // base_unit) * base_unit}px ou {((value // base_unit) + 1) * base_unit}px)",
+                    })
+
+        # CSS-in-JS numeric values
+        for match in spacing_js_pattern.finditer(line):
+            value = int(match.group(1))
+            if value > 0 and value % base_unit != 0 and value not in checked_values:
+                checked_values.add(value)
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "spacing",
+                    "found": f"{value} (CSS-in-JS)",
+                    "suggestion": f"Use múltiplo de {base_unit} (ex: {(value // base_unit) * base_unit} ou {((value // base_unit) + 1) * base_unit})",
+                })
+
+        # Tailwind: scale value * 4 = px
+        for match in tailwind_pattern.finditer(line):
+            scale = int(match.group(1))
+            px_value = scale * 4
+            if px_value > 0 and px_value % base_unit != 0:
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "spacing",
+                    "found": f"{match.group(0)} ({px_value}px)",
+                    "suggestion": f"Use múltiplo de {base_unit}px (ex: {(px_value // base_unit) * base_unit}px ou {((px_value // base_unit) + 1) * base_unit}px)",
+                })
+
+    return violations
+
+
+def scan_copywriting(filepath, lines):
+    """Encontra CTAs genéricos."""
+    violations = []
+    # Build pattern for matching generic CTAs in JS strings
+    ctas_pattern = "|".join(re.escape(cta) for cta in GENERIC_CTAS)
+    # React props: label="Submit", label='Submit'
+    react_prop_pattern = re.compile(
+        r"""(?:label|buttonText|title|placeholder|aria-label)\s*=\s*['"](%s)['"]""" % ctas_pattern,
+        re.IGNORECASE,
+    )
+
+    for lineno, line in enumerate(lines, 1):
+        # Busca em conteúdo de texto entre tags ou em atributos
+        text_matches = re.findall(r">([^<]+)<", line)
+        attr_matches = re.findall(r"(?:label|title|placeholder|aria-label)\s*=\s*[\"']([^\"']+)[\"']", line, re.IGNORECASE)
+
+        for text in text_matches + attr_matches:
+            text_lower = text.strip().lower()
+            if text_lower in GENERIC_CTAS:
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "copywriting",
+                    "found": text.strip(),
+                    "suggestion": "Use texto de ação específico (ex: 'Criar conta' em vez de 'Submit')",
+                })
+
+        # JSX text: >Submit< (no spaces around, single word)
+        for match in re.finditer(r">\s*(%s)\s*<" % ctas_pattern, line, re.IGNORECASE):
+            found = match.group(1).strip()
+            # Avoid duplicate if already caught by text_matches above
+            if found.lower() not in {t.strip().lower() for t in text_matches}:
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "copywriting",
+                    "found": found,
+                    "suggestion": "Use texto de ação específico (ex: 'Criar conta' em vez de 'Submit')",
+                })
+
+        # React props: label="Submit"
+        for match in react_prop_pattern.finditer(line):
+            found = match.group(1).strip()
+            # Avoid duplicate if already caught by attr_matches above
+            if found.lower() not in {t.strip().lower() for t in attr_matches}:
+                violations.append({
+                    "file": filepath,
+                    "line": lineno,
+                    "type": "copywriting",
+                    "found": found,
+                    "suggestion": "Use texto de ação específico (ex: 'Criar conta' em vez de 'Submit')",
+                })
+
+    return violations
+
+
+def walk_source(src_dir):
+    """Percorre diretório fonte e retorna arquivos escaneáveis."""
+    files = []
+    for root, _dirs, filenames in os.walk(src_dir):
+        # Ignora node_modules, .git, dist, build
+        parts = root.split(os.sep)
+        if any(p in {"node_modules", ".git", "dist", "build", ".next", "__pycache__"} for p in parts):
+            continue
+        for fname in filenames:
+            ext = os.path.splitext(fname)[1].lower()
+            if ext in SCANNABLE_EXTENSIONS:
+                files.append(os.path.join(root, fname))
+    return files
+
+
+def run_audit(design_path, src_dir, checks=None):
+    """Executa auditoria completa."""
+    contract = parse_design_md(design_path)
+    all_checks = {"colors", "typography", "spacing", "copywriting"}
+    active_checks = {checks} if checks else all_checks
+
+    files = walk_source(src_dir)
+    if not files:
+        print(f"Aviso: nenhum arquivo escaneável encontrado em {src_dir}", file=sys.stderr)
+        return []
+
+    all_violations = []
+    for filepath in files:
+        if _is_binary(filepath):
+            continue
+        try:
+            with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+        except (IOError, OSError):
+            continue
+
+        if "colors" in active_checks and contract["colors"]:
+            all_violations.extend(scan_colors(filepath, lines, contract["colors"]))
+        if "typography" in active_checks and contract["fonts"]:
+            all_violations.extend(scan_typography(filepath, lines, contract["fonts"]))
+        if "spacing" in active_checks:
+            all_violations.extend(scan_spacing(filepath, lines, contract["spacing_base"]))
+        if "copywriting" in active_checks:
+            all_violations.extend(scan_copywriting(filepath, lines))
+
+    return all_violations
+
+
+def format_violations(violations, fmt="table"):
+    """Formata e imprime violações."""
+    if not violations:
+        print("\n  Nenhuma violação encontrada. Contrato de design respeitado!\n")
+        return
+
+    if fmt == "json":
+        print(json.dumps(violations, indent=2, ensure_ascii=False))
+        return
+
+    print(f"\n  {len(violations)} violação(ões) encontrada(s):\n")
+
+    # Agrupa por tipo
+    by_type = {}
+    for v in violations:
+        by_type.setdefault(v["type"], []).append(v)
+
+    for vtype, items in by_type.items():
+        print(f"  [{vtype.upper()}] ({len(items)} violações)")
+        for item in items:
+            print(f"    {item['file']}:{item['line']}")
+            print(f"      Encontrado: {item['found']}")
+            print(f"      Sugestão: {item['suggestion']}")
+        print()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Scanner de violações do contrato de design.",
+        epilog="""Exemplos:
+  python3 audit.py --design .hefesto/DESIGN.md --src src/
+  python3 audit.py --design .hefesto/DESIGN.md --src src/ --check colors
+  python3 audit.py --design .hefesto/DESIGN.md --src src/ -f json
+""",
+    )
+    parser.add_argument("--design", required=True, help="Caminho para DESIGN.md")
+    parser.add_argument("--src", required=True, help="Diretório fonte para escanear")
+    parser.add_argument(
+        "--check",
+        choices=["colors", "typography", "spacing", "copywriting"],
+        default=None,
+        help="Verificar apenas um tipo específico",
+    )
+    parser.add_argument(
+        "-f", "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Formato de saída (padrão: table)",
+    )
+
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.design):
+        print(f"Erro: DESIGN.md não encontrado: {args.design}", file=sys.stderr)
+        sys.exit(1)
+
+    if not os.path.isdir(args.src):
+        print(f"Erro: diretório fonte não encontrado: {args.src}", file=sys.stderr)
+        sys.exit(1)
+
+    violations = run_audit(args.design, args.src, args.check)
+    format_violations(violations, args.format)
+
+    # Exit code não-zero se há violações
+    if violations:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/hefesto-design/scripts/contrast.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Verificador de contraste WCAG 2.1 para o Hefesto.
+
+Calcula ratio de contraste entre cores e valida conformidade com WCAG AA/AAA.
+Pode verificar pares individuais ou extrair cores de um DESIGN.md.
+"""
+
+import argparse
+import re
+import sys
+
+
+def parse_hex(color):
+    """Converte cor hexadecimal para (R, G, B) em 0-255.
+
+    Aceita formatos: #RGB, #RRGGBB, #RRGGBBAA (ignora alpha).
+    """
+    color = color.strip().lstrip("#")
+    if len(color) == 3:
+        color = "".join(c * 2 for c in color)
+    elif len(color) == 8:
+        color = color[:6]  # ignora alpha
+    elif len(color) != 6:
+        raise ValueError(f"Cor hexadecimal inválida: #{color}")
+
+    try:
+        r = int(color[0:2], 16)
+        g = int(color[2:4], 16)
+        b = int(color[4:6], 16)
+    except ValueError:
+        raise ValueError(f"Cor hexadecimal inválida: #{color}")
+
+    return r, g, b
+
+
+def relative_luminance(r, g, b):
+    """Calcula luminância relativa conforme WCAG 2.1.
+
+    sRGB para linear: if c <= 0.04045: c/12.92 else: ((c+0.055)/1.055)^2.4
+    L = 0.2126*R + 0.7152*G + 0.0722*B
+    """
+    def linearize(c):
+        c = c / 255.0
+        if c <= 0.04045:
+            return c / 12.92
+        return ((c + 0.055) / 1.055) ** 2.4
+
+    rl = linearize(r)
+    gl = linearize(g)
+    bl = linearize(b)
+    return 0.2126 * rl + 0.7152 * gl + 0.0722 * bl
+
+
+def contrast_ratio(color1, color2):
+    """Calcula ratio de contraste entre duas cores hex.
+
+    Retorna ratio como float (ex: 4.5).
+    """
+    r1, g1, b1 = parse_hex(color1)
+    r2, g2, b2 = parse_hex(color2)
+
+    l1 = relative_luminance(r1, g1, b1)
+    l2 = relative_luminance(r2, g2, b2)
+
+    lighter = max(l1, l2)
+    darker = min(l1, l2)
+
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def check_wcag(ratio):
+    """Verifica conformidade WCAG para um ratio."""
+    return {
+        "aa_normal": ratio >= 4.5,
+        "aa_large": ratio >= 3.0,
+        "aaa": ratio >= 7.0,
+    }
+
+
+def _pass_fail(ok):
+    return "PASSA" if ok else "FALHA"
+
+
+def format_result(fg, bg, ratio, wcag):
+    """Formata resultado de verificação."""
+    return (
+        f"  {fg} sobre {bg}\n"
+        f"    Ratio: {ratio:.1f}:1 | "
+        f"AA normal: {_pass_fail(wcag['aa_normal'])} | "
+        f"AA grande: {_pass_fail(wcag['aa_large'])} | "
+        f"AAA: {_pass_fail(wcag['aaa'])}"
+    )
+
+
+def check_pair(fg, bg):
+    """Verifica um par de cores e imprime resultado."""
+    ratio = contrast_ratio(fg, bg)
+    wcag = check_wcag(ratio)
+    print(format_result(fg, bg, ratio, wcag))
+    return wcag
+
+
+def extract_design_colors(design_path):
+    """Extrai cores da seção 'Contrato de Cores' do DESIGN.md.
+
+    Retorna dict com listas de cores foreground e background.
+    """
+    try:
+        with open(design_path, "r", encoding="utf-8") as f:
+            content = f.read()
+    except FileNotFoundError:
+        print(f"Erro: arquivo não encontrado: {design_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # Encontra seção de cores
+    colors_section = ""
+    in_section = False
+    for line in content.split("\n"):
+        if re.match(r"^#{1,6}\s+.*(?:contrato\s+de\s+cores|cores|paleta|colors)", line, re.IGNORECASE):
+            in_section = True
+            continue
+        if in_section and re.match(r"^#{1,6}\s+", line) and "cor" not in line.lower() and "color" not in line.lower() and "paleta" not in line.lower():
+            break
+        if in_section:
+            colors_section += line + "\n"
+
+    # Extrai todas as cores hex
+    hex_colors = re.findall(r"#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b", colors_section)
+    hex_colors = list(dict.fromkeys(hex_colors))  # remove duplicatas mantendo ordem
+
+    if not hex_colors:
+        print("Aviso: nenhuma cor hexadecimal encontrada na seção 'Contrato de Cores'.", file=sys.stderr)
+
+    return hex_colors
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Verificador de contraste WCAG 2.1.",
+        epilog="""Exemplos:
+  python3 contrast.py "#1a1a2e" "#ffffff"
+  python3 contrast.py --fg "#6366f1" --bg "#ffffff" --bg-dark "#1a1a2e"
+  python3 contrast.py --design .hefesto/DESIGN.md
+""",
+    )
+    parser.add_argument("color1", nargs="?", help="Cor de primeiro plano (hex)")
+    parser.add_argument("color2", nargs="?", help="Cor de fundo (hex)")
+    parser.add_argument("--fg", help="Cor de primeiro plano (hex)")
+    parser.add_argument("--bg", help="Cor de fundo claro (hex)")
+    parser.add_argument("--bg-dark", help="Cor de fundo escuro (hex)")
+    parser.add_argument("--design", help="Caminho para DESIGN.md para verificar todos os pares")
+
+    args = parser.parse_args()
+
+    print()
+
+    if args.design:
+        colors = extract_design_colors(args.design)
+        if len(colors) < 2:
+            print("Erro: pelo menos 2 cores são necessárias para verificar contraste.", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"  Verificando {len(colors)} cores de {args.design}\n")
+        failures = 0
+        total = 0
+        for i, fg in enumerate(colors):
+            for bg in colors[i + 1:]:
+                ratio = contrast_ratio(fg, bg)
+                wcag = check_wcag(ratio)
+                total += 1
+                if not wcag["aa_normal"]:
+                    failures += 1
+                print(format_result(fg, bg, ratio, wcag))
+
+        print(f"\n  Resumo: {total} pares verificados, {total - failures} passam AA normal, {failures} falham.\n")
+
+    elif args.fg:
+        if not args.bg:
+            parser.error("--bg é obrigatório quando --fg é usado.")
+
+        check_pair(args.fg, args.bg)
+        if args.bg_dark:
+            check_pair(args.fg, args.bg_dark)
+        print()
+
+    elif args.color1 and args.color2:
+        check_pair(args.color1, args.color2)
+        print()
+
+    else:
+        parser.error("Informe duas cores, use --fg/--bg, ou --design.")
+
+
+if __name__ == "__main__":
+    main()