bps-kit 1.0.1 → 1.0.2

package/templates/vault/skill-sentinel/scripts/analyzers/performance.py

@@ -0,0 +1,164 @@
+"""
+Analyzer de performance.
+
+Verifica: chamadas API sequenciais, caching, N+1 queries,
+connection reuse, retry/backoff, timeouts.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+def analyze(skill_data: Dict[str, Any]) -> Tuple[float, List[Dict[str, Any]]]:
+    """Analisa performance de uma skill. Retorna (score, findings)."""
+    score = 100.0
+    findings: List[Dict[str, Any]] = []
+    skill_name = skill_data["name"]
+    skill_path = Path(skill_data["path"])
+
+    has_retry = False
+    has_timeout = False
+    has_caching = False
+    has_connection_pool = False
+    has_async = False
+    has_concurrency = False
+
+    api_call_files = []
+
+    for rel_path in skill_data.get("python_files", []):
+        filepath = skill_path / rel_path
+        if not filepath.exists():
+            continue
+        try:
+            source = filepath.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        # Detectar patterns de performance
+        if re.search(r'(?:retry|backoff|MAX_RETRIES|RETRY_BACKOFF)', source, re.I):
+            has_retry = True
+        if re.search(r'(?:timeout|REQUEST_TIMEOUT)', source, re.I):
+            has_timeout = True
+        if re.search(r'(?:cache|lru_cache|functools\.cache|_cache)', source, re.I):
+            has_caching = True
+        if re.search(r'(?:session|Session\(\)|httpx\.Client)', source, re.I):
+            has_connection_pool = True
+        if re.search(r'(?:async\s+def|asyncio|aiohttp|httpx\.AsyncClient)', source):
+            has_async = True
+        if re.search(r'(?:concurrent|ThreadPool|ProcessPool|asyncio\.gather|--concurrency)', source, re.I):
+            has_concurrency = True
+
+        # Contar chamadas API (requests.get/post, httpx, etc)
+        api_calls = len(re.findall(
+            r'(?:requests\.\w+|httpx\.\w+|self\.\w*(?:get|post|put|delete|patch))\s*\(',
+            source
+        ))
+        if api_calls > 0:
+            api_call_files.append((rel_path, api_calls))
+
+        # Detectar N+1 patterns (loop com query SQL dentro)
+        # Analise linha-a-linha para evitar backtracking em regex DOTALL
+        lines = source.splitlines()
+        in_for_loop = False
+        for line_text in lines:
+            stripped = line_text.strip()
+            if stripped.startswith("for ") and stripped.endswith(":"):
+                in_for_loop = True
+            elif in_for_loop and stripped and not stripped[0].isspace() and not line_text[0].isspace():
+                in_for_loop = False
+            elif in_for_loop and re.search(r'(?:SELECT|\.execute)\s*\(', stripped):
+                findings.append({
+                    "skill_name": skill_name,
+                    "dimension": "performance",
+                    "severity": "medium",
+                    "category": "n_plus_1",
+                    "title": f"Possivel N+1 query em {rel_path}",
+                    "description": "Loop com query SQL pode causar muitas chamadas ao banco",
+                    "file_path": rel_path,
+                    "recommendation": "Carregar dados em batch antes do loop",
+                    "effort": "medium",
+                    "impact": "high",
+                })
+                score -= 8
+                break
+
+        # Criar conexao dentro de loop (analise simples)
+        has_connect_in_loop = False
+        in_for_loop = False
+        for line_text in lines:
+            stripped = line_text.strip()
+            if stripped.startswith("for ") and stripped.endswith(":"):
+                in_for_loop = True
+            elif in_for_loop and stripped and not line_text[0].isspace():
+                in_for_loop = False
+            elif in_for_loop and "_connect()" in stripped:
+                has_connect_in_loop = True
+                break
+
+        if has_connect_in_loop:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "performance",
+                "severity": "medium",
+                "category": "connection_per_iteration",
+                "title": f"Conexao criada dentro de loop em {rel_path}",
+                "file_path": rel_path,
+                "recommendation": "Mover _connect() para fora do loop, reutilizar conexao",
+                "effort": "low",
+                "impact": "high",
+            })
+            score -= 5
+
+    # Verificar ausencia de boas praticas
+    if not has_retry and api_call_files:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "performance",
+            "severity": "medium",
+            "category": "no_retry",
+            "title": "Sem retry/backoff para chamadas API",
+            "description": f"Encontradas chamadas API em {len(api_call_files)} arquivo(s) sem mecanismo de retry",
+            "recommendation": "Implementar retry com exponential backoff (ex: tenacity, ou manual)",
+            "effort": "medium",
+            "impact": "high",
+        })
+        score -= 10
+
+    if not has_timeout and api_call_files:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "performance",
+            "severity": "medium",
+            "category": "no_timeout",
+            "title": "Sem timeout configurado para chamadas HTTP",
+            "recommendation": "Adicionar timeout= em todas as chamadas requests/httpx",
+            "effort": "low",
+            "impact": "medium",
+        })
+        score -= 5
+
+    if not has_connection_pool and len(api_call_files) > 2:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "performance",
+            "severity": "low",
+            "category": "no_connection_reuse",
+            "title": "Sem reuso de conexoes HTTP",
+            "description": "Multiplos arquivos fazem chamadas HTTP sem Session/Client compartilhado",
+            "recommendation": "Usar requests.Session() ou httpx.Client() para reutilizar conexoes",
+            "effort": "low",
+            "impact": "medium",
+        })
+        score -= 3
+
+    # Bonus
+    if has_retry:
+        score = min(100.0, score + 5)
+    if has_async or has_concurrency:
+        score = min(100.0, score + 5)
+    if has_caching:
+        score = min(100.0, score + 3)
+
+    return max(0.0, min(100.0, score)), findings

package/templates/vault/skill-sentinel/scripts/analyzers/security.py

@@ -0,0 +1,189 @@
+"""
+Analyzer de seguranca.
+
+Verifica: secrets hardcoded, SQL injection, validacao de input,
+HTTPS enforcement, tokens em logs, padroes de autenticacao.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from config import SECRET_EXCEPTIONS, SECRET_PATTERNS, SQL_INJECTION_PATTERNS
+
+
+def _check_secrets(source: str, rel_path: str, skill_name: str) -> List[Dict[str, Any]]:
+    """Verifica patterns de secrets hardcoded."""
+    findings = []
+    for i, line in enumerate(source.splitlines(), 1):
+        for pattern in SECRET_PATTERNS:
+            if pattern.search(line):
+                # Checar se eh excecao conhecida
+                is_exception = any(exc in line for exc in SECRET_EXCEPTIONS)
+                if is_exception:
+                    continue
+                findings.append({
+                    "skill_name": skill_name,
+                    "dimension": "security",
+                    "severity": "critical",
+                    "category": "hardcoded_secret",
+                    "title": f"Possivel secret hardcoded em {rel_path}:{i}",
+                    "description": "Credencial ou token encontrado no codigo-fonte. "
+                                   "Mover para variavel de ambiente.",
+                    "file_path": rel_path,
+                    "line_number": i,
+                    "recommendation": "Usar os.environ.get() ou arquivo .env (nao versionado)",
+                    "effort": "low",
+                    "impact": "high",
+                })
+    return findings
+
+
+def _check_sql_injection(source: str, rel_path: str, skill_name: str) -> List[Dict[str, Any]]:
+    """Verifica uso de f-strings/format em queries SQL."""
+    findings = []
+    for i, line in enumerate(source.splitlines(), 1):
+        for pattern in SQL_INJECTION_PATTERNS:
+            if pattern.search(line):
+                findings.append({
+                    "skill_name": skill_name,
+                    "dimension": "security",
+                    "severity": "high",
+                    "category": "sql_injection",
+                    "title": f"Possivel SQL injection em {rel_path}:{i}",
+                    "description": "Interpolacao de string em query SQL. Usar queries parametrizadas (?)",
+                    "file_path": rel_path,
+                    "line_number": i,
+                    "recommendation": "Substituir f-string/format por query parametrizada: cursor.execute(sql, [param])",
+                    "effort": "low",
+                    "impact": "high",
+                })
+    return findings
+
+
+def _check_https(source: str, rel_path: str, skill_name: str) -> List[Dict[str, Any]]:
+    """Verifica se URLs usam HTTP em vez de HTTPS."""
+    findings = []
+    http_pattern = re.compile(r'["\']http://(?!localhost|127\.0\.0\.1|0\.0\.0\.0)')
+    for i, line in enumerate(source.splitlines(), 1):
+        if http_pattern.search(line):
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "security",
+                "severity": "medium",
+                "category": "insecure_http",
+                "title": f"URL HTTP insegura em {rel_path}:{i}",
+                "description": "Uso de HTTP em vez de HTTPS para comunicacao externa.",
+                "file_path": rel_path,
+                "line_number": i,
+                "recommendation": "Trocar http:// por https://",
+                "effort": "low",
+                "impact": "medium",
+            })
+    return findings
+
+
+def _check_token_in_logs(source: str, rel_path: str, skill_name: str) -> List[Dict[str, Any]]:
+    """Verifica se tokens/secrets aparecem em print/logging."""
+    findings = []
+    log_pattern = re.compile(
+        r'(?:print|logging\.\w+|logger\.\w+)\s*\(.*(?:token|secret|password|key|credential)',
+        re.I
+    )
+    for i, line in enumerate(source.splitlines(), 1):
+        if log_pattern.search(line):
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "security",
+                "severity": "high",
+                "category": "token_in_log",
+                "title": f"Possivel token em log em {rel_path}:{i}",
+                "description": "Dados sensiveis podem estar sendo logados.",
+                "file_path": rel_path,
+                "line_number": i,
+                "recommendation": "Nao logar tokens/secrets. Usar mascaramento ou remover do log.",
+                "effort": "low",
+                "impact": "high",
+            })
+    return findings
+
+
+def _check_input_validation(source: str, rel_path: str, skill_name: str) -> List[Dict[str, Any]]:
+    """Verifica se argumentos CLI sao validados."""
+    findings = []
+    # Se usa argparse mas nao tem choices/type/nargs restritivos, e warning leve
+    if "argparse" in source and "add_argument" in source:
+        # Verificar se ao menos alguns args tem type= ou choices=
+        args_count = source.count("add_argument")
+        typed_count = len(re.findall(r'add_argument\([^)]*(?:type=|choices=)', source))
+        if args_count > 3 and typed_count == 0:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "security",
+                "severity": "low",
+                "category": "weak_input_validation",
+                "title": f"Validacao fraca de argumentos CLI em {rel_path}",
+                "description": f"{args_count} argumentos sem type= ou choices=",
+                "file_path": rel_path,
+                "recommendation": "Adicionar type= e choices= nos argumentos do argparse",
+                "effort": "low",
+                "impact": "low",
+            })
+    return findings
+
+
+def analyze(skill_data: Dict[str, Any]) -> Tuple[float, List[Dict[str, Any]]]:
+    """Analisa seguranca de uma skill. Retorna (score, findings)."""
+    score = 100.0
+    findings: List[Dict[str, Any]] = []
+    skill_name = skill_data["name"]
+    skill_path = Path(skill_data["path"])
+
+    has_auth_module = False
+    uses_env_vars = False
+
+    for rel_path in skill_data.get("python_files", []):
+        filepath = skill_path / rel_path
+        if not filepath.exists():
+            continue
+
+        try:
+            source = filepath.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        if "auth" in rel_path.lower():
+            has_auth_module = True
+        if "os.environ" in source or "os.getenv" in source or "dotenv" in source:
+            uses_env_vars = True
+
+        # Checks
+        secret_findings = _check_secrets(source, rel_path, skill_name)
+        findings.extend(secret_findings)
+        score -= len([f for f in secret_findings if f["severity"] == "critical"]) * 20
+        score -= len([f for f in secret_findings if f["severity"] == "high"]) * 10
+
+        sql_findings = _check_sql_injection(source, rel_path, skill_name)
+        findings.extend(sql_findings)
+        score -= len(sql_findings) * 15
+
+        https_findings = _check_https(source, rel_path, skill_name)
+        findings.extend(https_findings)
+        score -= len(https_findings) * 5
+
+        token_findings = _check_token_in_logs(source, rel_path, skill_name)
+        findings.extend(token_findings)
+        score -= len(token_findings) * 10
+
+        input_findings = _check_input_validation(source, rel_path, skill_name)
+        findings.extend(input_findings)
+        score -= len(input_findings) * 2
+
+    # Bonus por boas praticas
+    if has_auth_module:
+        score = min(100.0, score + 5)
+    if uses_env_vars:
+        score = min(100.0, score + 5)
+
+    return max(0.0, min(100.0, score)), findings

package/templates/vault/skill-sentinel/scripts/config.py

@@ -0,0 +1,158 @@
+"""
+Configuracao central da skill Sentinel.
+
+Paths, thresholds de analise, pesos de scoring e padroes de seguranca.
+Importado por todos os outros scripts.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+# -- Paths --------------------------------------------------------------------
+ROOT_DIR = Path(__file__).resolve().parent.parent
+SCRIPTS_DIR = ROOT_DIR / "scripts"
+DATA_DIR = ROOT_DIR / "data"
+REPORTS_DIR = DATA_DIR / "reports"
+DB_PATH = DATA_DIR / "sentinel.db"
+
+# Raiz do ecossistema de skills
+SKILLS_ROOT = ROOT_DIR.parent
+
+# Garante que diretorios existem
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+
+# -- Skill Discovery ----------------------------------------------------------
+# Locais onde skills podem estar (relativo a SKILLS_ROOT)
+SKILL_SEARCH_PATHS: List[Path] = [
+    SKILLS_ROOT,                           # skills de primeiro nivel
+    SKILLS_ROOT / ".claude" / "skills",    # skills built-in do Claude
+]
+
+# Subdiretorios a escanear recursivamente (para skills aninhadas)
+SKILL_MAX_DEPTH = 3
+
+# Diretorios a ignorar durante o scan
+IGNORE_DIRS = {
+    "__pycache__", ".git", "node_modules", ".venv", "venv",
+    "data", "exports", "static", ".claude",
+    "skill-sentinel",  # nao auditar a si mesmo
+}
+
+# -- Scoring Weights (devem somar 1.0) ----------------------------------------
+DIMENSION_WEIGHTS: Dict[str, float] = {
+    "code_quality":   0.20,
+    "security":       0.20,
+    "performance":    0.15,
+    "governance":     0.15,
+    "documentation":  0.15,
+    "dependencies":   0.15,
+}
+
+# -- Score Labels --------------------------------------------------------------
+SCORE_LABELS: List[Tuple[int, int, str]] = [
+    (90, 100, "Excelente"),
+    (75, 89,  "Bom"),
+    (50, 74,  "Adequado"),
+    (25, 49,  "Precisa melhorar"),
+    (0,  24,  "Critico"),
+]
+
+def get_score_label(score: float) -> str:
+    """Retorna label textual para um score numerico."""
+    for low, high, label in SCORE_LABELS:
+        if low <= score <= high:
+            return label
+    return "Desconhecido"
+
+# -- Code Quality Thresholds ---------------------------------------------------
+MAX_FUNCTION_LINES = 50
+MAX_CYCLOMATIC_COMPLEXITY = 10
+MAX_FILE_LINES = 500
+MIN_DOCSTRING_COVERAGE = 0.5
+
+# Penalidades (pontos subtraidos de 100)
+PENALTY_HIGH_COMPLEXITY = 5       # por funcao acima do limite
+PENALTY_LONG_FUNCTION = 3         # por funcao acima do limite
+PENALTY_LONG_FILE = 5             # por arquivo acima do limite
+PENALTY_NO_DOCSTRING = 1          # por funcao/classe sem docstring
+PENALTY_BARE_EXCEPT = 8           # por bare except
+PENALTY_BROAD_EXCEPT = 3          # por except Exception sem log
+
+# -- Security Patterns ---------------------------------------------------------
+SECRET_PATTERNS: List[re.Pattern] = [
+    re.compile(r'(?:password|passwd|pwd)\s*=\s*["\'][^"\']{8,}["\']', re.I),
+    re.compile(r'(?:secret|secret_key)\s*=\s*["\'][^"\']{8,}["\']', re.I),
+    re.compile(r'(?:api_key|apikey|api_secret)\s*=\s*["\'][^"\']{8,}["\']', re.I),
+    re.compile(r'(?:access_token|auth_token)\s*=\s*["\'][^"\']{8,}["\']', re.I),
+    re.compile(r'(?:private_key|ssh_key)\s*=\s*["\']', re.I),
+    re.compile(r'(?:aws_access_key_id|aws_secret)\s*=\s*["\']', re.I),
+]
+
+# Padroes que sao excepcoes conhecidas (nao sao secrets reais)
+SECRET_EXCEPTIONS: List[str] = [
+    "546c25a59c58ad7",  # Imgur public anonymous upload key
+]
+
+SQL_INJECTION_PATTERNS: List[re.Pattern] = [
+    re.compile(r'f["\'].*(?:SELECT|INSERT|UPDATE|DELETE|DROP|CREATE).*\{', re.I),
+    re.compile(r'\.format\(.*(?:SELECT|INSERT|UPDATE|DELETE|DROP|CREATE)', re.I),
+    re.compile(r'%\s*\(.*(?:SELECT|INSERT|UPDATE|DELETE|DROP|CREATE)', re.I),
+]
+
+# -- Performance Thresholds ----------------------------------------------------
+MAX_SEQUENTIAL_API_CALLS = 5  # sugerir batching se > este numero
+WARN_NO_RETRY = True          # avisar se nao tem retry/backoff
+WARN_NO_TIMEOUT = True        # avisar se requests sem timeout
+
+# -- Governance Maturity Levels ------------------------------------------------
+GOVERNANCE_LEVELS: Dict[int, str] = {
+    0: "Nenhuma",
+    1: "Basica (action logging)",
+    2: "Padrao (logging + rate limiting)",
+    3: "Completa (logging + rate limit + confirmacoes)",
+    4: "Avancada (completa + alertas + trends)",
+}
+
+# -- Documentation Required Sections -------------------------------------------
+SKILL_MD_REQUIRED_SECTIONS: List[str] = [
+    "name",          # frontmatter
+    "description",   # frontmatter
+]
+
+SKILL_MD_RECOMMENDED_SECTIONS: List[str] = [
+    "version",       # frontmatter
+    "instalacao",    # ou "installation"
+    "comandos",      # ou "commands", "uso", "usage"
+    "governanca",    # ou "governance"
+    "referencias",   # ou "references"
+]
+
+# -- Severity Ordering ---------------------------------------------------------
+SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
+
+# -- Gap Analysis Taxonomy -----------------------------------------------------
+CAPABILITY_TAXONOMY: Dict[str, str] = {
+    "data-extraction":       "Extracao de dados de fontes externas",
+    "social-media":          "Integracao com redes sociais",
+    "messaging":             "Sistemas de mensageria",
+    "government-data":       "Dados governamentais e registros publicos",
+    "web-automation":        "Automacao de browser e interacoes web",
+    "api-integration":       "Integracao com APIs externas",
+    "analytics":             "Analise de dados e metricas",
+    "content-management":    "Gestao e criacao de conteudo",
+    "testing":               "Testes automatizados e QA",
+    "monitoring":            "Monitoramento e alertas",
+    "ci-cd":                 "Integracao e deploy continuo",
+    "documentation-gen":     "Geracao automatica de documentacao",
+    "data-pipeline":         "ETL e pipelines de dados",
+    "scheduling":            "Agendamento e cron jobs",
+    "notification":          "Notificacoes multi-canal",
+    "email-integration":     "Integracao com email",
+    "database-management":   "Gestao de bancos de dados",
+    "file-management":       "Gestao de arquivos e storage",
+    "security-audit":        "Auditoria de seguranca",
+    "cost-optimization":     "Otimizacao de custos e recursos",
+}

package/templates/vault/skill-sentinel/scripts/cost_optimizer.py

@@ -0,0 +1,146 @@
+"""
+Cost Optimizer: analisa padroes que impactam consumo de tokens e custos de API.
+
+Identifica SKILL.md muito grandes (impacto direto em tokens consumidos pelo Claude),
+output verboso, oportunidades de cache, e padrao de chamadas API.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+def analyze(skill_data: Dict[str, Any]) -> Tuple[float, List[Dict[str, Any]]]:
+    """
+    Analisa custos de uma skill. Retorna (score, findings).
+    Score alto = skill eficiente em custo.
+    """
+    score = 100.0
+    findings: List[Dict[str, Any]] = []
+    skill_name = skill_data["name"]
+    skill_path = Path(skill_data["path"])
+
+    # -- 1. Tamanho do SKILL.md (impacto direto em context window) ---------------
+    skill_md_lines = skill_data.get("skill_md_lines", 0)
+
+    if skill_md_lines > 500:
+        cost_impact = "alto"
+        severity = "high"
+        score -= 20
+    elif skill_md_lines > 300:
+        cost_impact = "medio"
+        severity = "medium"
+        score -= 10
+    elif skill_md_lines > 150:
+        cost_impact = "baixo"
+        severity = "low"
+        score -= 3
+    else:
+        cost_impact = None
+
+    if cost_impact:
+        # Estimar tokens: ~1.3 tokens por palavra, ~10 palavras por linha
+        est_tokens = int(skill_md_lines * 10 * 1.3)
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "cost",
+            "severity": severity,
+            "category": "large_skill_md",
+            "title": f"SKILL.md com {skill_md_lines} linhas (~{est_tokens:,} tokens estimados)",
+            "description": f"Impacto de custo {cost_impact}. Cada ativacao desta skill "
+                           f"consome ~{est_tokens:,} tokens do context window.",
+            "recommendation": "Mover detalhes para references/ e manter SKILL.md < 200 linhas. "
+                              "Usar progressive disclosure: SKILL.md = overview, "
+                              "references/ = detalhes lidos sob demanda.",
+            "effort": "medium",
+            "impact": "high",
+        })
+
+    # -- 2. References muito grandes ----------------------------------------------
+    ref_dir = skill_path / "references"
+    if ref_dir.exists():
+        for ref_file in ref_dir.glob("*.md"):
+            try:
+                lines = len(ref_file.read_text(encoding="utf-8", errors="replace").splitlines())
+            except OSError:
+                continue
+            if lines > 300:
+                est_tokens = int(lines * 10 * 1.3)
+                findings.append({
+                    "skill_name": skill_name,
+                    "dimension": "cost",
+                    "severity": "low",
+                    "category": "large_reference",
+                    "title": f"Reference grande: {ref_file.name} ({lines} linhas, ~{est_tokens:,} tokens)",
+                    "description": "Se carregado inteiro no contexto, consome muitos tokens.",
+                    "file_path": f"references/{ref_file.name}",
+                    "recommendation": "Adicionar indice/TOC no inicio. Instruir no SKILL.md "
+                                      "para ler apenas secoes relevantes.",
+                    "effort": "low",
+                    "impact": "medium",
+                })
+                score -= 3
+
+    # -- 3. Output verboso dos scripts --------------------------------------------
+    for rel_path in skill_data.get("python_files", []):
+        filepath = skill_path / rel_path
+        if not filepath.exists():
+            continue
+        try:
+            source = filepath.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        # Contar prints verbosos
+        import re
+        print_count = len(re.findall(r'\bprint\s*\(', source))
+        lines = len(source.splitlines())
+
+        # Se >10% das linhas sao prints, eh verboso
+        if lines > 20 and print_count > 0 and (print_count / lines) > 0.08:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "cost",
+                "severity": "low",
+                "category": "verbose_output",
+                "title": f"Output verboso em {rel_path} ({print_count} prints em {lines} linhas)",
+                "description": "Output excessivo consome tokens do context window quando "
+                               "Claude le a saida do script.",
+                "file_path": rel_path,
+                "recommendation": "Usar --verbose flag ou logging levels em vez de prints fixos. "
+                                  "Retornar JSON conciso por padrao.",
+                "effort": "low",
+                "impact": "medium",
+            })
+            score -= 3
+
+    # -- 4. Verificar se scripts retornam JSON estruturado vs texto livre -----------
+    has_json_output = False
+    for rel_path in skill_data.get("python_files", []):
+        filepath = skill_path / rel_path
+        if not filepath.exists():
+            continue
+        try:
+            source = filepath.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if "json.dumps" in source or "json.dump" in source:
+            has_json_output = True
+            break
+
+    if not has_json_output and skill_data.get("file_count", 0) > 3:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "cost",
+            "severity": "low",
+            "category": "no_structured_output",
+            "title": "Sem output JSON estruturado",
+            "description": "Scripts que retornam JSON sao mais eficientes para o Claude processar "
+                           "do que texto livre.",
+            "recommendation": "Adicionar opcao --json para output estruturado em scripts principais",
+            "effort": "low",
+            "impact": "medium",
+        })
+        score -= 5
+
+    return max(0.0, min(100.0, score)), findings