bps-kit 1.0.1 → 1.0.2

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

@@ -0,0 +1,134 @@
+"""
+Analyzer cross-skill.
+
+Identifica padroes compartilhados entre skills que poderiam ser
+extraidos em modulos comuns, reducindo duplicacao.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+
+def analyze_cross_skill(all_skills: List[Dict[str, Any]]) -> Tuple[float, List[Dict[str, Any]]]:
+    """
+    Analisa padroes cross-skill. Diferente dos outros analyzers,
+    recebe TODAS as skills e retorna findings globais.
+    Retorna (score_medio, findings).
+    """
+    findings: List[Dict[str, Any]] = []
+
+    if len(all_skills) < 2:
+        return 100.0, findings
+
+    # -- 1. Detectar modulos duplicados (mesmo nome de arquivo em multiplas skills) ---
+    module_presence: Dict[str, List[str]] = {}
+    for skill in all_skills:
+        for rel_path in skill.get("python_files", []):
+            filename = Path(rel_path).name
+            module_presence.setdefault(filename, []).append(skill["name"])
+
+    shared_modules = {k: v for k, v in module_presence.items() if len(v) > 1}
+
+    if shared_modules:
+        for module, skills in shared_modules.items():
+            if module in ("__init__.py", "requirements.txt"):
+                continue
+            findings.append({
+                "skill_name": "cross-skill",
+                "dimension": "cross_skill",
+                "severity": "medium",
+                "category": "duplicated_module",
+                "title": f"Modulo '{module}' presente em {len(skills)} skills",
+                "description": f"Skills: {', '.join(skills)}. "
+                               "Potencial para extrair em modulo compartilhado.",
+                "recommendation": f"Avaliar se {module} pode ser extraido para uma lib compartilhada "
+                                  f"(ex: shared-core/scripts/{module})",
+                "effort": "medium",
+                "impact": "high",
+            })
+
+    # -- 2. Padroes de Database (mesmo pattern _connect) --------------------------
+    db_skills = [s for s in all_skills if s.get("has_db")]
+    if len(db_skills) > 1:
+        findings.append({
+            "skill_name": "cross-skill",
+            "dimension": "cross_skill",
+            "severity": "low",
+            "category": "shared_db_pattern",
+            "title": f"{len(db_skills)} skills com modulo db.py independente",
+            "description": f"Skills: {', '.join(s['name'] for s in db_skills)}. "
+                           "Padrao Database._connect() com WAL mode eh repetido.",
+            "recommendation": "Criar classe BaseDatabase em shared-core com _connect(), "
+                              "e cada skill herdar e definir apenas suas tabelas.",
+            "effort": "medium",
+            "impact": "medium",
+        })
+
+    # -- 3. Padroes de Config (mesmo pattern ROOT_DIR) ----------------------------
+    config_skills = [s for s in all_skills if s.get("has_config")]
+    if len(config_skills) > 1:
+        findings.append({
+            "skill_name": "cross-skill",
+            "dimension": "cross_skill",
+            "severity": "info",
+            "category": "shared_config_pattern",
+            "title": f"{len(config_skills)} skills com config.py similar",
+            "description": "Padrao de paths (ROOT_DIR, DATA_DIR, etc) repetido.",
+            "recommendation": "Considerar base_config.py compartilhado com paths padrao",
+            "effort": "low",
+            "impact": "low",
+        })
+
+    # -- 4. Skills sem governanca vs com governanca --------------------------------
+    gov_skills = [s for s in all_skills if s.get("has_governance")]
+    no_gov_skills = [s for s in all_skills if not s.get("has_governance")]
+
+    if gov_skills and no_gov_skills:
+        findings.append({
+            "skill_name": "cross-skill",
+            "dimension": "cross_skill",
+            "severity": "medium",
+            "category": "inconsistent_governance",
+            "title": "Governanca inconsistente entre skills",
+            "description": f"Com governanca: {', '.join(s['name'] for s in gov_skills)}. "
+                           f"Sem governanca: {', '.join(s['name'] for s in no_gov_skills)}.",
+            "recommendation": "Padronizar governanca em todas as skills. "
+                              "Extrair GovernanceManager para modulo compartilhado.",
+            "effort": "medium",
+            "impact": "high",
+        })
+
+    # -- 5. Padroes de export (json/csv/parquet) -----------------------------------
+    export_skills = []
+    for skill in all_skills:
+        for rel_path in skill.get("python_files", []):
+            if "export" in rel_path.lower():
+                export_skills.append(skill["name"])
+                break
+
+    if len(export_skills) > 1:
+        findings.append({
+            "skill_name": "cross-skill",
+            "dimension": "cross_skill",
+            "severity": "low",
+            "category": "shared_export_pattern",
+            "title": f"{len(export_skills)} skills com modulo de export",
+            "description": f"Skills: {', '.join(export_skills)}",
+            "recommendation": "Considerar export utils compartilhados (json/csv/parquet)",
+            "effort": "low",
+            "impact": "low",
+        })
+
+    # Score baseado na quantidade de duplicacao encontrada
+    score = 100.0
+    for f in findings:
+        if f["severity"] == "medium":
+            score -= 8
+        elif f["severity"] == "low":
+            score -= 3
+        elif f["severity"] == "info":
+            score -= 1
+
+    return max(0.0, min(100.0, score)), findings

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

@@ -0,0 +1,121 @@
+"""
+Analyzer de dependencias.
+
+Verifica: requirements.txt existe, versoes pinadas, dependencias nao usadas,
+dependencias importadas mas nao listadas.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Set, Tuple
+
+
+def _extract_imports(source: str) -> Set[str]:
+    """Extrai nomes de pacotes importados de um arquivo Python."""
+    imports = set()
+    for match in re.finditer(r'^(?:import|from)\s+(\w+)', source, re.MULTILINE):
+        pkg = match.group(1)
+        # Ignorar stdlib e imports relativos
+        if pkg not in {
+            "os", "sys", "re", "json", "ast", "pathlib", "datetime", "typing",
+            "uuid", "hashlib", "sqlite3", "argparse", "collections", "functools",
+            "time", "math", "io", "csv", "logging", "traceback", "textwrap",
+            "urllib", "http", "shutil", "subprocess", "tempfile", "threading",
+            "concurrent", "asyncio", "dataclasses", "enum", "abc", "copy",
+            "config", "db", "governance", "scanner", "analyzers",  # modulos internos
+        }:
+            imports.add(pkg)
+    return imports
+
+
+def _normalize_pkg_name(name: str) -> str:
+    """Normaliza nome de pacote para comparacao (- e _ sao equivalentes)."""
+    return name.lower().replace("-", "_")
+
+
+def analyze(skill_data: Dict[str, Any]) -> Tuple[float, List[Dict[str, Any]]]:
+    """Analisa dependencias 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"])
+
+    requirements = skill_data.get("requirements", [])
+    reqs_path = skill_path / "scripts" / "requirements.txt"
+
+    # Sem requirements.txt
+    if not reqs_path.exists():
+        # Se nao tem Python files, nao precisa
+        if skill_data.get("file_count", 0) > 0:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "dependencies",
+                "severity": "medium",
+                "category": "missing_requirements",
+                "title": "requirements.txt nao encontrado",
+                "recommendation": "Criar scripts/requirements.txt com todas as dependencias",
+                "effort": "low",
+                "impact": "medium",
+            })
+            score -= 15
+        return max(0.0, score), findings
+
+    # Verificar versoes pinadas
+    unpinned = [r for r in requirements if not r.get("pinned")]
+    if unpinned and len(requirements) > 1:
+        names = ", ".join(r["name"] for r in unpinned[:5])
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "dependencies",
+            "severity": "low",
+            "category": "unpinned_versions",
+            "title": f"{len(unpinned)} dependencia(s) sem versao pinada",
+            "description": f"Pacotes sem ==: {names}",
+            "recommendation": "Pinar versoes com == para reproducibilidade (ex: requests==2.31.0)",
+            "effort": "low",
+            "impact": "medium",
+        })
+        score -= min(10, len(unpinned) * 2)
+
+    # Verificar deps importadas vs listadas
+    all_imports: Set[str] = set()
+    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
+        all_imports.update(_extract_imports(source))
+
+    listed_names = {_normalize_pkg_name(r["name"]) for r in requirements}
+
+    # Importadas mas nao listadas (possivel dep faltando)
+    # Mapear nomes de import para nomes de pacote (alguns diferem)
+    import_to_pkg = {
+        "PIL": "pillow",
+        "cv2": "opencv_python",
+        "bs4": "beautifulsoup4",
+        "yaml": "pyyaml",
+        "dotenv": "python_dotenv",
+        "playwright": "playwright",
+    }
+
+    for imp in all_imports:
+        pkg_name = _normalize_pkg_name(import_to_pkg.get(imp, imp))
+        if pkg_name not in listed_names:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "dependencies",
+                "severity": "low",
+                "category": "unlisted_dependency",
+                "title": f"Pacote '{imp}' importado mas nao em requirements.txt",
+                "recommendation": f"Adicionar {imp} ao requirements.txt",
+                "effort": "low",
+                "impact": "low",
+            })
+            score -= 2
+
+    return max(0.0, min(100.0, score)), findings

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

@@ -0,0 +1,189 @@
+"""
+Analyzer de documentacao.
+
+Verifica completude do SKILL.md, secoes obrigatorias, frontmatter,
+triggers, exemplos e cobertura de reference files.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from config import SKILL_MD_RECOMMENDED_SECTIONS, SKILL_MD_REQUIRED_SECTIONS
+
+
+def _check_frontmatter(content: str) -> Dict[str, bool]:
+    """Verifica presenca de campos no frontmatter YAML."""
+    has = {}
+    if content.startswith("---"):
+        end = content.find("---", 3)
+        if end > 0:
+            fm = content[3:end].lower()
+            has["name"] = "name:" in fm
+            has["description"] = "description:" in fm or "description:" in fm
+            has["version"] = "version:" in fm
+    return has
+
+
+def _check_sections(content: str) -> Dict[str, bool]:
+    """Verifica presenca de secoes recomendadas no corpo."""
+    lower = content.lower()
+    sections = {}
+    section_keywords = {
+        "instalacao": ["instalacao", "installation", "instalação", "setup", "pip install"],
+        "comandos": ["comandos", "commands", "uso", "usage", "cli", "como usar"],
+        "governanca": ["governanca", "governance", "governança", "rate limit", "audit"],
+        "referencias": ["referencias", "references", "referências", "reference"],
+    }
+    for key, keywords in section_keywords.items():
+        sections[key] = any(kw in lower for kw in keywords)
+    return sections
+
+
+def _check_triggers(description: str) -> Dict[str, Any]:
+    """Verifica se description tem triggers adequados."""
+    if not description:
+        return {"has_triggers": False, "trigger_count": 0}
+    # Contar palavras-chave de trigger
+    words = re.findall(r'\b\w+\b', description.lower())
+    return {
+        "has_triggers": len(words) > 10,
+        "trigger_count": len(words),
+        "has_bilingual": any(w in description.lower() for w in ["use when", "use esta", "triggers on"]),
+    }
+
+
+def analyze(skill_data: Dict[str, Any]) -> Tuple[float, List[Dict[str, Any]]]:
+    """Analisa documentacao 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"])
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "critical",
+            "category": "missing_skill_md",
+            "title": "SKILL.md nao encontrado",
+            "recommendation": "Criar SKILL.md com frontmatter YAML e documentacao completa",
+            "effort": "medium",
+            "impact": "high",
+        })
+        return 0.0, findings
+
+    try:
+        content = skill_md.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return 0.0, findings
+
+    lines = len(content.splitlines())
+
+    # Frontmatter
+    fm = _check_frontmatter(content)
+    if not fm.get("name"):
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "high",
+            "category": "missing_frontmatter_name",
+            "title": "Frontmatter sem campo 'name'",
+            "recommendation": "Adicionar 'name: skill-name' no frontmatter YAML",
+            "effort": "low",
+            "impact": "high",
+        })
+        score -= 20
+
+    if not fm.get("description"):
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "high",
+            "category": "missing_frontmatter_description",
+            "title": "Frontmatter sem campo 'description'",
+            "recommendation": "Adicionar 'description:' com trigger keywords no frontmatter YAML",
+            "effort": "medium",
+            "impact": "high",
+        })
+        score -= 20
+
+    if not fm.get("version"):
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "low",
+            "category": "missing_version",
+            "title": "Sem versao no frontmatter",
+            "recommendation": "Adicionar 'version: 1.0.0' no frontmatter YAML",
+            "effort": "low",
+            "impact": "low",
+        })
+        score -= 3
+
+    # Triggers
+    desc = skill_data.get("description", "")
+    trigger_info = _check_triggers(desc)
+    if not trigger_info["has_triggers"]:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "medium",
+            "category": "weak_triggers",
+            "title": "Description com poucas palavras-chave de trigger",
+            "description": f"Apenas {trigger_info['trigger_count']} palavras. "
+                           "Mais keywords = mais chance de ativacao correta pelo Claude.",
+            "recommendation": "Expandir description com mais trigger keywords em PT-BR e EN",
+            "effort": "low",
+            "impact": "high",
+        })
+        score -= 10
+
+    # Secoes do corpo
+    sections = _check_sections(content)
+    for section_key in ["instalacao", "comandos", "governanca", "referencias"]:
+        if not sections.get(section_key):
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "documentation",
+                "severity": "low",
+                "category": f"missing_section_{section_key}",
+                "title": f"Secao '{section_key}' nao encontrada no SKILL.md",
+                "recommendation": f"Adicionar secao de {section_key} no SKILL.md",
+                "effort": "low",
+                "impact": "low",
+            })
+            score -= 3
+
+    # Reference files
+    ref_files = skill_data.get("reference_files", [])
+    if not ref_files and skill_data.get("has_references_dir"):
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "low",
+            "category": "empty_references",
+            "title": "Diretorio references/ vazio",
+            "recommendation": "Adicionar documentacao de referencia em references/",
+            "effort": "medium",
+            "impact": "low",
+        })
+        score -= 5
+
+    # SKILL.md tamanho: muito curto eh ruim
+    if lines < 20:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "documentation",
+            "severity": "medium",
+            "category": "short_skill_md",
+            "title": f"SKILL.md muito curto ({lines} linhas)",
+            "recommendation": "Expandir SKILL.md com exemplos, workflows e detalhes de uso",
+            "effort": "medium",
+            "impact": "medium",
+        })
+        score -= 10
+
+    return max(0.0, min(100.0, score)), findings

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

@@ -0,0 +1,153 @@
+"""
+Analyzer de governanca.
+
+Avalia maturidade de governanca: logging, rate limits, confirmacoes,
+audit trail, alertas. Baseado no padrao de referencia do instagram/scripts/governance.py.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from config import GOVERNANCE_LEVELS
+
+
+def _detect_governance_level(skill_data: Dict[str, Any], skill_path: Path) -> int:
+    """Detecta nivel de maturidade de governanca."""
+    has_action_log = False
+    has_rate_limit = False
+    has_confirmation = False
+    has_warnings = 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 re.search(r'(?:action_log|log_action|audit_log)', source, re.I):
+            has_action_log = True
+        if re.search(r'(?:rate_limit|check_rate|RateLimitExceeded)', source, re.I):
+            has_rate_limit = True
+        if re.search(r'(?:requires_confirmation|confirmation_request|--confirm)', source, re.I):
+            has_confirmation = True
+        if re.search(r'(?:warning_threshold|RATE_LIMIT_WARNING|warnings?\s*\.append)', source, re.I):
+            has_warnings = True
+
+    if has_action_log and has_rate_limit and has_confirmation and has_warnings:
+        return 4
+    elif has_action_log and has_rate_limit and has_confirmation:
+        return 3
+    elif has_action_log and has_rate_limit:
+        return 2
+    elif has_action_log:
+        return 1
+    return 0
+
+
+def analyze(skill_data: Dict[str, Any]) -> Tuple[float, List[Dict[str, Any]]]:
+    """Analisa governanca de uma skill. Retorna (score, findings)."""
+    findings: List[Dict[str, Any]] = []
+    skill_name = skill_data["name"]
+    skill_path = Path(skill_data["path"])
+
+    level = _detect_governance_level(skill_data, skill_path)
+    score = level * 25.0  # 0=0, 1=25, 2=50, 3=75, 4=100
+
+    # Findings baseados no nivel
+    if level == 0:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "governance",
+            "severity": "high",
+            "category": "no_governance",
+            "title": "Sem modulo de governanca",
+            "description": "A skill nao tem nenhum mecanismo de governanca. "
+                           "Isso significa que acoes nao sao rastreadas e nao ha controle de taxa.",
+            "recommendation": "Criar governance.py com GovernanceManager (action log + rate limiting). "
+                              "Referenciar instagram/scripts/governance.py como modelo.",
+            "effort": "medium",
+            "impact": "high",
+        })
+
+    if level < 2:
+        findings.append({
+            "skill_name": skill_name,
+            "dimension": "governance",
+            "severity": "medium",
+            "category": "no_rate_limiting",
+            "title": "Sem rate limiting",
+            "description": "Chamadas API nao tem controle de taxa, risco de bloqueio por excesso de uso.",
+            "recommendation": "Implementar check_rate_limit() antes de chamadas a APIs externas",
+            "effort": "medium",
+            "impact": "high",
+        })
+
+    if level < 3:
+        has_destructive = 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 re.search(r'(?:delete|publish|send|post|remove)', source, re.I):
+                has_destructive = True
+                break
+
+        if has_destructive:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "governance",
+                "severity": "medium",
+                "category": "no_confirmation",
+                "title": "Acoes destrutivas sem confirmacao",
+                "description": "Skill tem acoes que modificam dados externos mas sem 2-step confirmation",
+                "recommendation": "Implementar padrao de confirmacao: requires_confirmation() + create_confirmation_request()",
+                "effort": "medium",
+                "impact": "high",
+            })
+
+    if level >= 3:
+        # Bonus: verificar se o audit log tem consulta
+        has_cli = 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 "get_recent_actions" in source or "__main__" in source:
+                has_cli = True
+
+        if not has_cli:
+            findings.append({
+                "skill_name": skill_name,
+                "dimension": "governance",
+                "severity": "info",
+                "category": "no_audit_cli",
+                "title": "Audit log sem CLI de consulta",
+                "recommendation": "Adicionar modo CLI para consultar acoes recentes: python governance.py",
+                "effort": "low",
+                "impact": "low",
+            })
+
+    # Registrar nivel como info
+    findings.append({
+        "skill_name": skill_name,
+        "dimension": "governance",
+        "severity": "info",
+        "category": "governance_level",
+        "title": f"Nivel de governanca: {level} - {GOVERNANCE_LEVELS.get(level, '?')}",
+        "description": f"Maturidade de governanca detectada: nivel {level}/4",
+    })
+
+    return max(0.0, min(100.0, score)), findings