agent-master-devsecops 0.0.0-stage → 3.9.0

package/docs/playbooks/PLAYBOOK_CIRCUIT_BREAKER_LLM.md

@@ -0,0 +1,58 @@
+# ⚡ PLAYBOOK DE SRE: CIRCUIT BREAKER INTELIGENTE MULTI-PROVEDOR PARA LLMS
+
+---
+playbook: sre-circuit-breaker-llm
+versao: 1.0.0
+proprietario: Agente SRE & Observabilidade (AGENT_SRE.md)
+referencia: AGDEV-9 (I-10) / Padrão de Engenharia de Resiliência Michael Nygard
+---
+
+## 🎯 1. OBJETIVO & ESCOPO
+Este playbook estabelece a estratégia de continuidade de negócio e tolerância a falhas para agentes de inteligência artificial diante de instabilidades de provedores de LLM externos (erros HTTP 429 - Rate Limit, 503 - Service Unavailable, 504 - Gateway Timeout ou latência excessiva).
+
+---
+
+## 🔄 2. MÁQUINA DE ESTADOS DO CIRCUIT BREAKER (TRANSIÇÃO LINEAR DE FLUXO)
+
+Cada provedor de IA possui seu próprio disjuntor com 3 estados canônicos, operando através de uma sequência linear determinística em texto:
+
+1. **Estado Inicial: CLOSED (Fechado - Operação Normal)**
+   - O tráfego de requisições flui normalmente para o provedor primário.
+   - Cada chamada bem-sucedida mantém o circuito fechado e zera o contador de erros.
+   - Chamadas com falha consecutiva (erros HTTP 429, 500, 502, 503, 504 ou timeout) incrementam o contador.
+   - **Gatilho de Transição:** Ao atingir o limite de 3 falhas consecutivas (`failureThreshold >= 3`), o estado transita linearmente para **OPEN**.
+
+2. **Estado de Proteção: OPEN (Aberto - Circuito Rompido)**
+   - O tráfego para este provedor é bloqueado de forma imediata (Fail-Fast local), sem efetuar chamadas de rede externas.
+   - Toda requisição é desviada instantaneamente para o próximo provedor da cadeia de fallback.
+   - Um temporizador de recuperação (`recoveryTimeout`) de 30 segundos é iniciado.
+   - **Gatilho de Transição:** Quando o tempo decorrido atinge ou supera 30 segundos (`tempo >= 30s`), o estado avança linearmente para **HALF_OPEN**.
+
+3. **Estado de Sondagem: HALF_OPEN (Meio-Aberto - Teste de Recuperação)**
+   - O circuito autoriza uma única requisição de teste para avaliar se o provedor remoto se recuperou da instabilidade.
+   - **Bifurcação Linear de Retorno:**
+     - **Caso de Sucesso:** Se a requisição de teste for concluída com êxito, o disjuntor é rearmado, o contador de falhas é resetado para zero e o estado retorna para **CLOSED**.
+     - **Caso de Falha:** Se a requisição de teste falhar, o disjuntor desarma novamente, o temporizador de cooldown de 30 segundos é reiniciado e o estado retorna para **OPEN**.
+
+---
+
+## ⛓️ 3. CADEIA CANÔNICA DE FALLBACK MULTI-PROVEDOR
+A ordem de comutação automática respeita a relação de capacidade, latência e custo:
+
+1. **Primário (Fronteira Analítica)**: Anthropic (`claude-3-5-sonnet`) / OpenAI (`gpt-4o`)
+   - Em caso de HTTP 429 ou 5xx após 3 tentativas:
+2. **Secundário (Alta Velocidade / Fallback de Fronteira)**: Groq (`llama-3.3-70b-versatile` / `deepseek-r1-distill-llama-70b`)
+   - Em caso de falha de conexão:
+3. **Terciário (Resiliência Local / Offline)**: Ollama (`qwen2.5-coder:7b` / `llama3.1:8b`)
+   - Execução local em hardware do desenvolvedor com o prompt compactado (`AGENT_ORCHESTRATOR_COMPACTO.md`).
+
+---
+
+## 📊 4. OBSERVABILIDADE & ALERTAS PROMETHEUS
+O módulo expõe as seguintes métricas canônicas:
+- `llm_circuit_breaker_state{provider="anthropic"}`: 0=CLOSED, 1=OPEN, 2=HALF_OPEN
+- `llm_circuit_breaker_fallbacks_total{from="anthropic",to="groq"}`: contador acumulado de chaveamentos
+- `llm_provider_latency_seconds{provider="groq"}`: histograma de latência
+
+### Alerta SRE: `LLMAllCircuitsOpen`
+Se todos os provedores da cadeia estiverem com circuito `OPEN`, o agente emite notificação de severidade CRÍTICA no Jira e ativa o modo local estrito.

package/docs/playbooks/PLAYBOOK_OPENTELEMETRY_TRACING.md

@@ -0,0 +1,58 @@
+# 📡 PLAYBOOK DE SRE: TRACING DISTRIBUÍDO COM OPENTELEMETRY & ANÁLISE DE FLAMEGRAPHS
+
+---
+playbook: sre-opentelemetry-tracing
+versao: 1.0.0
+proprietario: Agente SRE & Observabilidade (AGENT_SRE.md)
+referencia: AGDEV-24 (I-8) / RFC W3C TraceContext
+---
+
+## 🎯 1. OBJETIVO & ESCOPO
+Este playbook estabelece o procedimento operacional padrão (SOP) para instrumentação, propagação de contexto de rastreamento distribuído e diagnóstico de latência crítica em requisições lentas (P95/P99) utilizando a especificação **OpenTelemetry (OTel)** e **W3C TraceContext**.
+
+---
+
+## 🌐 2. PADRÃO W3C TRACECONTEXT (`traceparent`)
+Toda requisição externa, chamada entre microserviços ou handover entre agentes DEVE propagar o cabeçalho canônico:
+
+```http
+traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+              │  └───────────────┬────────────────┘ └───────┬──────┘ └─┬┘
+           Versão             Trace ID                   Span ID      Flags (01 = Sampled)
+```
+
+1. **Trace ID (16 bytes / 32 hex chars)**: Identificador único global da transação.
+2. **Span ID (8 bytes / 16 hex chars)**: Identificador da operação específica em execução.
+3. **Parent Span ID**: Vincula a sub-operação à operação chamadora para montagem do DAG de execução.
+
+---
+
+## 🔥 3. ANÁLISE DE FLAMEGRAPHS & GARGALOS (CRITICAL PATH)
+A visualização em Flamegraph permite identificar visualmente onde o tempo da requisição foi consumido:
+
+```text
+=== FLAMEGRAPH DISTRIBUÍDO [Trace: 6be1fab9a7fb6cef75cb1eb13e532b47] (105ms) ===
+[01] █████████ architect_plan (25ms)
+[02] ██████████████████████ devsecops_implementation (60ms) [GARGALO: 57%]
+[03] █████ revisor_audit (15ms)
+[04] ████████████████████████████████████████ user_goal_execution (105ms)
+```
+
+### Regras de Classificação de Gargalo:
+- **CRÍTICA**: Span individual consome $\ge 70\%$ do tempo total da transação.
+- **ALTA**: Span individual consome entre $40\%$ e $69\%$ do tempo total.
+- **MÉDIA**: Span individual excede 50ms em chamadas de I/O de banco de dados ou RPCs.
+
+---
+
+## 🛠️ 4. FLUXO OPERACIONAL DE AUTO-REMEDIAÇÃO SRE
+Quando o alerta de latência P99 (`LatencyDegradedP99 > 500ms`) for disparado no Prometheus:
+
+1. **Localização do Trace**: Consultar os spans com `status.code === 'ERROR'` ou maior duração no Tempo/Jaeger via `traceId`.
+2. **Isolamento de Causa-Raiz (RCA)**:
+   - Se o span for de banco de dados (`db.system === 'sqlite' | 'postgres'`): inspecionar queries sem índice ou contenção de lock.
+   - Se o span for de LLM (`model.provider === 'openai' | 'groq'`): verificar latência de rede e acionar Circuit Breaker (I-10).
+   - Se o span for de compilação ou build: escalonar recursos de CPU/RAM.
+3. **Ação Automatizada**:
+   - Purgar caches intermediários ou conexões travadas.
+   - Registrar incidente rastreável no Jira com o flamegraph ASCII anexado.

package/package.json

@@ -1,6 +1,47 @@
-{
-  "name": "agent-master-devsecops",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "agent-master-devsecops",
+  "version": "3.9.0",
+  "description": "Hub Universal de Agentes Autônomos de Engenharia & Governança Prescritiva com Servidor MCP Nativo",
+  "main": "scripts/mcp_server.js",
+  "bin": {
+    "agent-master-devsecops": "scripts/bootstrap_cli.js",
+    "agent-master-mcp": "scripts/mcp_server.js",
+    "agent-master-init": "scripts/bootstrap_cli.js",
+    "agent-bootstrap": "scripts/bootstrap_cli.js",
+    "agent-inspector": "scripts/web_inspector.js",
+    "agent-onboard": "scripts/smart_onboarding.js",
+    "agent-mine-ideas": "scripts/domain_idea_miner.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*test*.js",
+    "onboard": "node scripts/smart_onboarding.js",
+    "mine:ideas": "node scripts/domain_idea_miner.js",
+    "mcp": "node scripts/mcp_server.js",
+    "ui": "node scripts/web_inspector.js",
+    "sync:confluence": "node scripts/confluence_sync.js",
+    "track:jira": "node scripts/jira_manager.js --track",
+    "standardize:kanban": "node scripts/jira_manager.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "devsecops",
+    "ai-agents",
+    "code-review",
+    "governance",
+    "prescriptive-autonomy",
+    "triad-sync",
+    "finops",
+    "late-binding",
+    "smart-onboarding"
+  ],
+  "author": "ContalApps",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ContalApps/agent-master-devsecops.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/a11y_auditor.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * scripts/a11y_auditor.js
+ * 
+ * Auditor de Acessibilidade Digital & Design Tokens — WCAG 2.1 AA (AGENT_UIUX / AGENT_QA).
+ * Inspeciona componentes HTML, JSX e TSX contra violações de acessibilidade, contraste,
+ * semântica WAI-ARIA, foco visível e padrões de usabilidade (Heurísticas de Nielsen).
+ * 
+ * Em estrita conformidade com a persona AGENT_UIUX.md e diretrizes de inclusão digital.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const WCAG_RULES = [
+  {
+    id: 'WCAG-1.1.1',
+    criterion: 'Non-text Content (Nível A)',
+    name: 'Imagem sem texto alternativo (alt)',
+    severity: 'CRÍTICA',
+    pattern: /<(?:img|Image)\b(?![^>]*\balt\s*=)[^>]*>/i,
+    issue: 'Elemento de imagem não possui o atributo "alt" para tecnologias assistivas.',
+    remediation: 'Adicione alt="Descrição da imagem" ou alt="" acompanhado de role="presentation" para imagens puramente decorativas.'
+  },
+  {
+    id: 'WCAG-4.1.2-BTN',
+    criterion: 'Name, Role, Value (Nível A)',
+    name: 'Botão interativo sem rótulo acessível',
+    severity: 'ALTA',
+    pattern: /<(?:button)\b(?![^>]*\b(?:aria-label|aria-labelledby|title)\s*=)[^>]*>\s*<(?:svg|i|span)\b[^>]*>\s*<\/(?:svg|i|span)>\s*<\/button>/i,
+    issue: 'Botão contendo apenas ícone sem aria-label, aria-labelledby ou texto acessível.',
+    remediation: 'Inclua aria-label="Ação do botão" ou texto acessível visível/oculto via classe sr-only.'
+  },
+  {
+    id: 'WCAG-1.3.1-INPUT',
+    criterion: 'Info and Relationships (Nível A)',
+    name: 'Campo de entrada (input) sem rótulo associado',
+    severity: 'CRÍTICA',
+    pattern: /<(?:input)\b(?![^>]*\b(?:type=["'](?:hidden|submit|button|image)["']))(?![^>]*\b(?:aria-label|aria-labelledby|id\s*=))[^>]*>/i,
+    issue: 'Elemento <input> não possui id para pareamento com <label htmlFor="..."> nem aria-label.',
+    remediation: 'Adicione um id único ao input pareado com <label htmlFor="id"> ou declare aria-label.'
+  },
+  {
+    id: 'WCAG-2.4.4-LINK',
+    criterion: 'Link Purpose (In Context) (Nível A)',
+    name: 'Link com texto vago ou não descritivo',
+    severity: 'MÉDIA',
+    pattern: /<a\b[^>]*>\s*(?:clique aqui|click here|saiba mais|read more|veja mais|link)\s*<\/a>/i,
+    issue: 'Texto de link ambíguo ("clique aqui", "saiba mais") que prejudica a navegação cega por links.',
+    remediation: 'Substitua por texto descritivo do destino (ex: "Consulte o catálogo de livros").'
+  },
+  {
+    id: 'WCAG-2.4.7-FOCUS',
+    criterion: 'Focus Visible (Nível AA)',
+    name: 'Supressão de contorno de foco sem anel acessível',
+    severity: 'ALTA',
+    pattern: /className=["'][^"']*\boutline-none\b(?![^"']*\b(?:focus-visible:|focus:ring|focus:border))[^"']*["']/i,
+    issue: 'Uso de outline-none sem definição de anel alternativo de foco (focus-visible / focus:ring).',
+    remediation: 'Mantenha o foco visível para usuários de teclado adicionando classes como "focus-visible:ring-2 focus-visible:ring-blue-500".'
+  },
+  {
+    id: 'WCAG-2.4.3-TABINDEX',
+    criterion: 'Focus Order (Nível A)',
+    name: 'Uso de tabindex positivo (anti-pattern)',
+    severity: 'MÉDIA',
+    pattern: /\btabIndex\s*=\s*(?:\{[1-9][0-9]*\}|["'][1-9][0-9]*["'])/i,
+    issue: 'tabindex maior que zero altera a ordem natural de tabulação do DOM.',
+    remediation: 'Utilize tabindex="0" para incluir o elemento no fluxo natural ou reorganize a ordem dos elementos no DOM.'
+  },
+  {
+    id: 'WCAG-3.1.1-LANG',
+    criterion: 'Language of Page (Nível A)',
+    name: 'Documento HTML sem atributo de idioma (lang)',
+    severity: 'ALTA',
+    pattern: /<html\b(?![^>]*\blang\s*=)[^>]*>/i,
+    issue: 'Tag <html> sem atributo lang, impedindo sintetizadores de voz de carregar a pronúncia correta.',
+    remediation: 'Declare o idioma principal do documento: <html lang="pt-BR">.'
+  }
+];
+
+class A11yAuditor {
+  constructor(rules = WCAG_RULES) {
+    this.rules = rules;
+  }
+
+  auditCode(code, filename = 'component.tsx') {
+    const lines = code.split('\n');
+    const violations = [];
+
+    // 1. Varredura por linha para regras com correspondência em linha única
+    lines.forEach((line, index) => {
+      const lineNum = index + 1;
+      for (const rule of this.rules) {
+        if (rule.pattern.test(line)) {
+          violations.push({
+            ruleId: rule.id,
+            wcagCriterion: rule.criterion,
+            name: rule.name,
+            severity: rule.severity,
+            line: lineNum,
+            snippet: line.trim().slice(0, 100),
+            issue: rule.issue,
+            remediation: rule.remediation
+          });
+        }
+      }
+    });
+
+    // 2. Varredura no bloco completo (para tags multilinhas)
+    for (const rule of this.rules) {
+      if (rule.pattern.global) {
+        const matches = code.matchAll(rule.pattern);
+        for (const match of matches) {
+          const charIndex = match.index || 0;
+          const lineNum = code.slice(0, charIndex).split('\n').length;
+          if (!violations.some(v => v.ruleId === rule.id && v.line === lineNum)) {
+            violations.push({
+              ruleId: rule.id,
+              wcagCriterion: rule.criterion,
+              name: rule.name,
+              severity: rule.severity,
+              line: lineNum,
+              snippet: match[0].trim().slice(0, 100),
+              issue: rule.issue,
+              remediation: rule.remediation
+            });
+          }
+        }
+      }
+    }
+
+    const criticalCount = violations.filter(v => v.severity === 'CRÍTICA').length;
+    const highCount = violations.filter(v => v.severity === 'ALTA').length;
+    const mediumCount = violations.filter(v => v.severity === 'MÉDIA').length;
+
+    let verdict = 'APROVADO';
+    if (criticalCount > 0 || highCount > 0) {
+      verdict = 'REPROVADO';
+    } else if (mediumCount > 0) {
+      verdict = 'COM RESSALVAS';
+    }
+
+    return {
+      filename,
+      wcagTarget: 'WCAG 2.1 Nível AA',
+      verdict,
+      status: verdict === 'APROVADO' ? 'PASSED' : 'FAILED',
+      summary: {
+        totalViolations: violations.length,
+        criticalCount,
+        highCount,
+        mediumCount
+      },
+      violations
+    };
+  }
+
+  formatReport(audit) {
+    let md = `## ♿ Relatório de Auditoria de Acessibilidade (WCAG 2.1 AA — AGENT UI/UX)\n\n`;
+    md += `**Alvo:** \`${audit.filename}\` | **Veredito:** ${audit.verdict === 'APROVADO' ? '✅ APROVADO' : audit.verdict === 'REPROVADO' ? '❌ REPROVADO' : '⚠️ COM RESSALVAS'}\n\n`;
+    md += `### 📊 Sumário Executivo de Inclusão\n`;
+    md += `- **Violações Críticas (Impede Leitor de Tela):** ${audit.summary.criticalCount}\n`;
+    md += `- **Violações Altas (Navegação/Foco):** ${audit.summary.highCount}\n`;
+    md += `- **Ressalvas Médias:** ${audit.summary.mediumCount}\n\n`;
+
+    if (audit.violations.length > 0) {
+      md += `### ⚠️ Apontamentos de Acessibilidade Detectados\n\n`;
+      md += `| Linha | Critério WCAG | Severidade | Problema | Remediação Recomendada |\n`;
+      md += `| :---: | :--- | :---: | :--- | :--- |\n`;
+      for (const v of audit.violations) {
+        md += `| ${v.line} | **${v.wcagCriterion}** (${v.ruleId}) | **${v.severity}** | ${v.issue} | ${v.remediation} |\n`;
+      }
+      md += '\n';
+    } else {
+      md += `> 🌟 **Componente Acessível:** Nenhuma violação detectada. O componente atende às diretrizes WCAG 2.1 AA.\n\n`;
+    }
+
+    return md;
+  }
+}
+
+module.exports = {
+  A11yAuditor,
+  WCAG_RULES
+};

package/scripts/ast_skeletonizer.js

@@ -0,0 +1,220 @@
+/**
+ * scripts/ast_skeletonizer.js
+ * 
+ * Extrator Canônico de Esqueleto de Código & Contratos de Interface (Rule 9 — Work Loop).
+ * "From other modules, read only what they expose (types, function signatures, schemas), never their inner code."
+ * 
+ * Remove corpos de métodos e implementações internas de classes, gerando um esqueleto com alta
+ * densidade semântica para prompts de agentes, economizando entre 80% e 92% de tokens de contexto.
+ * Suporta JavaScript/TypeScript, Java e Python.
+ */
+
+'use strict';
+
+class AstSkeletonizer {
+  constructor(options = {}) {
+    this.charsPerToken = options.charsPerToken || 3.8;
+  }
+
+  estimateTokens(text = '') {
+    if (!text) return 0;
+    return Math.max(1, Math.ceil(text.length / this.charsPerToken));
+  }
+
+  /**
+   * Esqueletiza código Java (Remove corpos de métodos mantendo anotações, assinaturas e interfaces)
+   */
+  skeletonizeJava(code = '') {
+    const lines = code.split(/\r?\n/);
+    const resultLines = [];
+    let insideMethodBody = false;
+    let braceDepth = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      if (!insideMethodBody) {
+        if (trimmed.startsWith('package ') || trimmed.startsWith('import ') || trimmed.startsWith('@') ||
+            trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') ||
+            trimmed.includes('class ') || trimmed.includes('interface ') || trimmed.includes('enum ') ||
+            trimmed === '' || trimmed === '}') {
+          resultLines.push(line);
+          continue;
+        }
+
+        const isMethodSignature = /\b(public|protected|private|static|final|default)\b.*\(.*\).*/.test(trimmed);
+        if (isMethodSignature) {
+          if (trimmed.endsWith('{')) {
+            const signature = line.substring(0, line.lastIndexOf('{')).trimEnd();
+            resultLines.push(`${signature} { /* implementation omitted */ }`);
+            insideMethodBody = true;
+            braceDepth = 1;
+            continue;
+          } else if (trimmed.endsWith(';')) {
+            resultLines.push(line);
+            continue;
+          }
+        }
+
+        resultLines.push(line);
+      } else {
+        for (const char of line) {
+          if (char === '{') braceDepth++;
+          if (char === '}') braceDepth--;
+        }
+        if (braceDepth <= 0) {
+          insideMethodBody = false;
+          braceDepth = 0;
+        }
+      }
+    }
+
+    return resultLines.join('\n');
+  }
+
+  /**
+   * Esqueletiza código JS/TS (Mantém exports, interfaces, types e assinaturas, remove corpos de função)
+   */
+  skeletonizeJsTs(code = '') {
+    const lines = code.split(/\r?\n/);
+    const resultLines = [];
+    let insideFunction = false;
+    let braceDepth = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      if (!insideFunction) {
+        // Preserva imports, declarações de classe, interfaces, types e comentários
+        if (trimmed.startsWith('import ') || trimmed.startsWith('export type ') || trimmed.startsWith('export interface ') ||
+            trimmed.startsWith('type ') || trimmed.startsWith('interface ') || trimmed.startsWith('//') ||
+            trimmed.startsWith('/*') || trimmed.startsWith('*') || (trimmed.startsWith('const ') && trimmed.includes('require(')) ||
+            trimmed.includes('class ') || trimmed === '' || trimmed === '}') {
+          resultLines.push(line);
+          continue;
+        }
+
+        // Detecta funções soltas ou métodos de classe com abertura de chaves
+        const isFuncOrMethod = /\b(function|async|get|set|static)\b|\b[\w$]+\s*\([^)]*\)\s*[:\w\s<>]*\{/.test(trimmed);
+        if (isFuncOrMethod && trimmed.includes('{')) {
+          const lastBrace = line.lastIndexOf('{');
+          const signature = line.substring(0, lastBrace).trimEnd();
+          resultLines.push(`${signature} { /* implementation */ }`);
+
+          // Checa se a função abriu e fechou na mesma linha
+          let lineDepth = 0;
+          for (let c = lastBrace; c < line.length; c++) {
+            if (line[c] === '{') lineDepth++;
+            if (line[c] === '}') lineDepth--;
+          }
+          if (lineDepth > 0) {
+            insideFunction = true;
+            braceDepth = lineDepth;
+          }
+          continue;
+        }
+
+        resultLines.push(line);
+      } else {
+        for (const char of line) {
+          if (char === '{') braceDepth++;
+          if (char === '}') braceDepth--;
+        }
+        if (braceDepth <= 0) {
+          insideFunction = false;
+          braceDepth = 0;
+        }
+      }
+    }
+
+    return resultLines.join('\n');
+  }
+
+  /**
+   * Esqueletiza código Python (Mantém defs, classes e docstrings; substitui corpos por ...)
+   */
+  skeletonizePython(code = '') {
+    const lines = code.split(/\r?\n/);
+    const resultLines = [];
+    let insideFunction = false;
+    let functionIndent = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+      const currentIndent = (line.match(/^\s*/) || [''])[0].length;
+
+      if (insideFunction) {
+        if (trimmed === '') continue;
+        if (currentIndent <= functionIndent && !trimmed.startsWith('#')) {
+          insideFunction = false;
+        } else {
+          // Preserva docstring de 1 linha logo após o def se houver
+          if ((trimmed.startsWith('"""') || trimmed.startsWith("'''")) && !resultLines[resultLines.length - 1].includes('...')) {
+            resultLines.push(line);
+            resultLines.push(' '.repeat(functionIndent + 4) + '...');
+          }
+          continue;
+        }
+      }
+
+      if (trimmed.startsWith('def ') && trimmed.endsWith(':')) {
+        resultLines.push(line);
+        insideFunction = true;
+        functionIndent = currentIndent;
+
+        // Se a próxima linha for docstring, será tratada na iteração seguinte; caso contrário insere ...
+        const nextLine = lines[i + 1] ? lines[i + 1].trim() : '';
+        if (!nextLine.startsWith('"""') && !nextLine.startsWith("'''")) {
+          resultLines.push(' '.repeat(functionIndent + 4) + '...');
+        }
+        continue;
+      }
+
+      resultLines.push(line);
+    }
+
+    return resultLines.join('\n');
+  }
+
+  skeletonize(code = '', language = 'javascript') {
+    const lang = String(language).toLowerCase().trim();
+    let skeleton = '';
+
+    if (lang === 'java' || lang === 'jvm') {
+      skeleton = this.skeletonizeJava(code);
+    } else if (lang.includes('python') || lang.includes('py')) {
+      skeleton = this.skeletonizePython(code);
+    } else {
+      skeleton = this.skeletonizeJsTs(code);
+    }
+
+    const originalTokens = this.estimateTokens(code);
+    const skeletonTokens = this.estimateTokens(skeleton);
+    const tokensSaved = Math.max(0, originalTokens - skeletonTokens);
+    const reductionPercent = originalTokens > 0 ? Math.round((tokensSaved / originalTokens) * 100) : 0;
+
+    return {
+      language: lang,
+      originalLines: code.split(/\r?\n/).length,
+      skeletonLines: skeleton.split(/\r?\n/).length,
+      originalTokens,
+      skeletonTokens,
+      tokensSaved,
+      reductionPercent,
+      skeletonCode: skeleton
+    };
+  }
+}
+
+function extractCodeSkeleton(code, language = 'javascript') {
+  const skeletonizer = new AstSkeletonizer();
+  return skeletonizer.skeletonize(code, language);
+}
+
+module.exports = {
+  AstSkeletonizer,
+  extractCodeSkeleton
+};