@mocoto/mahoraga 0.14.8 → 0.15.0

package/dist/analysts/php/scorers/scorer-php.js

@@ -1,4 +1,3 @@
-// SPDX-License-Identifier: MIT
 import { splitLines } from '../../../shared/helpers/index.js';
 import { detectorPhpBestPractices, detectorPhpSecurity } from '../detectors/index.js';
 export function pontuarPhp(src, relPath) {
@@ -8,7 +7,6 @@ export function pontuarPhp(src, relPath) {
     const strengths = [];
     const linhas = splitLines(src);
     const linesCount = linhas.length;
-    // Security score (40 points)
     let securityScore = 0;
     const securityMsgs = detectorPhpSecurity.aplicar(src, relPath);
     const securityCount = (securityMsgs ?? []).length;
@@ -20,7 +18,6 @@ export function pontuarPhp(src, relPath) {
         securityScore = Math.max(0, 40 - securityCount * 8);
         issues.push(`${securityCount} problema(s) de segurança`);
     }
-    // PSR/best practices score (35 points)
     let psrScore = 0;
     const bpMsgs = detectorPhpBestPractices.aplicar(src, relPath);
     const bpCount = (bpMsgs ?? []).length;
@@ -32,7 +29,6 @@ export function pontuarPhp(src, relPath) {
         psrScore = Math.max(0, 35 - bpCount * 5);
         issues.push(`${bpCount} desvio(s) de boas práticas`);
     }
-    // Complexity score (25 points)
     let complexityScore = 25;
     const fnMatches = src.matchAll(/(?:^|\n)\s*(?:public|private|protected|static)?\s*function\s+\w+\s*\([^)]*\)\s*(?::\s*\w+(?:\s*\|\s*\w+)*)?\s*\{/g);
     let hasComplex = false;
@@ -64,7 +60,6 @@ export function pontuarPhp(src, relPath) {
     else {
         strengths.push('Funções com complexidade adequada');
     }
-    // File size penalty
     if (linesCount > 500) {
         const penalty = Math.min(10, Math.floor((linesCount - 500) / 100));
         score -= penalty;

package/dist/analysts/plugins/analyst-formatter.js

@@ -1,10 +1,8 @@
-// @mahoraga-disable ml-deep-nesting
-// SPDX-License-Identifier: MIT
 import { messages } from '../../core/messages/index.js';
 import { formatarMarkdownMinimo, formatarPrettierMinimo } from '../../shared/formatters/index.js';
 import { extrairSupressoes, shouldSuppressOccurrence } from '../../shared/helpers/index.js';
 import { criarAnalista, criarOcorrencia } from '../../types/index.js';
-const disableEnv = process.env.SUKUNA_DISABLE_PLUGIN_FORMATADOR === '1';
+const disableEnv = process.env.MAHORAGA_DISABLE_PLUGIN_FORMATADOR === '1';
 function parserParaTipo(parser) {
     return `formatador-${parser}`;
 }
@@ -57,7 +55,6 @@ export const analistaFormatador = criarAnalista({
         if (disableEnv) {
             return null;
         }
-        // Para markdown, extrair supressões inline e passar ao formatter
         const isMarkdown = /\.(md|markdown)$/i.test(relPath);
         let res;
         if (isMarkdown) {
@@ -86,7 +83,6 @@ export const analistaFormatador = criarAnalista({
         }
         const linha = primeiraLinhaDiferente(src, res.formatted);
         const detalhes = [`primeira diferença na linha ${linha}`, res.reason ? `motivo: ${res.reason}` : null].filter(Boolean).join(', ');
-        // Manter como aviso (alinha com intenção de "check" sem mutação)
         return [msg(messages.FormatadorMensagens.naoFormatado(res.parser, detalhes || undefined), relPath, res.parser, messages.SeverityNiveis.warning, linha)];
     }
 });

package/dist/analysts/plugins/detector-documentation.js

@@ -20,20 +20,15 @@ export const analistaDocumentacao = {
         });
         const problemas = [];
         try {
-            // Detectar problemas por padrões de texto
             detectarPadroesDocumentacao(src, problemas, relPath);
-            // Detectar problemas via AST quando disponível
             if (ast) {
                 detectarProblemasDocumentacaoAST(ast, problemas);
             }
-            // Converter para ocorrências
             const ocorrencias = [];
-            // Agrupar por prioridade
             const porPrioridade = agruparPorPrioridade(problemas);
             for (const [prioridade, items] of Object.entries(porPrioridade)) {
                 if (items.length > 0) {
                     const nivel = mapearPrioridadeParaNivel(prioridade);
-                    // Ser mais relaxado com testes e arquivos de configuração
                     const nivelAjustado = (contextoArquivo.isTest || contextoArquivo.isConfiguracao) && nivel === 'aviso' ? 'info' : nivel;
                     const resumo = items.slice(0, 3).map(caminho => caminho.tipo).join(', ');
                     ocorrencias.push(criarOcorrencia({
@@ -45,7 +40,6 @@ export const analistaDocumentacao = {
                     }));
                 }
             }
-            // Aplicar supressões inline antes de retornar
             return filtrarOcorrenciasSuprimidas(ocorrencias, 'documentacao', src);
         }
         catch (erro) {
@@ -61,42 +55,30 @@ export const analistaDocumentacao = {
 };
 function detectarPadroesDocumentacao(src, problemas, relPath) {
     const linhas = src.split('\n');
-    // [ALVO] FILOSOFIA: Documentação é importante mas não deve poluir
-    // - Detectar apenas problemas reais, não ausência de JSDoc em código interno
-    // - Priorizar qualidade do código sobre quantidade de comentários
-    // - Arquivos de biblioteca pública precisam mais documentação que utils internos
-    // Verificar se é arquivo de biblioteca pública (requer documentação rigorosa)
     const isLibraryArquivo = relPath.includes('src/shared/') || relPath.includes('src/core/') || relPath.includes('lib/');
-    // Arquivos que não precisam JSDoc rigoroso
     const isInternalArquivo = relPath.includes('/cli/') || relPath.includes('/test') || relPath.includes('/spec') || relPath.includes('/__tests__/') || relPath.includes('/fixtures/') || relPath.includes('/mocks/') || relPath.includes('config.') || relPath.includes('setup.') || relPath.includes('/messages/');
     let temExportacaoPublica = false;
     let temJSDoc = false;
     let dentroDeJSDoc = false;
     linhas.forEach((linha, index) => {
         const numeroLinha = index + 1;
-        // Rastrear contexto JSDoc
         if (/\/\*\*/.test(linha)) {
             temJSDoc = true;
             dentroDeJSDoc = true;
         }
-        // Pular análise de problemas se estiver dentro de JSDoc ou linha começa com * (JSDoc)
         const linhaJSDoc = dentroDeJSDoc || /^\s*\*/.test(linha);
         if (linhaJSDoc) {
-            // Verificar fechamento depois de pular análise
             if (/\*\//.test(linha)) {
                 dentroDeJSDoc = false;
             }
-            return; // Não analisar código dentro de comentários JSDoc
+            return;
         }
-        // Detectar exportações
         if (/^export\s+(function|class|const|let|var|default)/.test(linha.trim())) {
             temExportacaoPublica = true;
         }
-        // Variáveis com nomes de uma letra (exceto loops, cast types, e contextos legítimos)
         const singleLetterMatch = /\b(const|let|var)\s+([a-z])\s*=/.exec(linha);
         if (singleLetterMatch && !/for\s*\(/.test(linha) && !/while\s*\(/.test(linha)) {
             const varNome = singleLetterMatch[2];
-            // Excluir variáveis legítimas: i, j, k em contexto de iteração, tipos (x as Type)
             const isLoopContext = /\b(i|j|k)\s*=\s*\d+/.test(linha) || /\b(i|j|k)\s*[+\-]=/.test(linha);
             const isTipoCast = /as\s+\w+/.test(linha) || /:\s*\w+\s*=/.test(linha);
             if (!isLoopContext && !isTipoCast) {
@@ -111,7 +93,6 @@ function detectarPadroesDocumentacao(src, problemas, relPath) {
                 });
             }
         }
-        // Números mágicos (não em arrays ou comparações simples)
         const numMagico = /\b(\d{2,})\b/.exec(linha);
         if (numMagico && !/(length|size|count)\s*[=><!]/.test(linha) && !/\[\s*\d+\s*\]/.test(linha) && parseInt(numMagico[1]) > 10) {
             problemas.push({
@@ -124,7 +105,6 @@ function detectarPadroesDocumentacao(src, problemas, relPath) {
                 sugestao: 'Extraia para constante nomeada com comentário'
             });
         }
-        // Comentários TODO antigos (aproximação heurística)
         if (/TODO.*\d{4}/.test(linha)) {
             const ano = /TODO.*(\d{4})/.exec(linha)?.[1];
             const anoAtual = new Date().getFullYear();
@@ -140,18 +120,14 @@ function detectarPadroesDocumentacao(src, problemas, relPath) {
                 });
             }
         }
-        // TypeScript: tipos 'any' sem comentário explicativo (exceto em strings literais)
         if (/:\s*any\b/.test(linha) && !/\/\/|\/\*/.test(linha)) {
-            // Verificar se não está dentro de string (ex: const code = 'x: any')
             const anyMatch = /:\s*any\b/.exec(linha);
             if (anyMatch) {
                 const position = anyMatch.index;
                 const before = linha.substring(0, position);
-                // Contar aspas antes da posição
                 const singleQuotes = (before.match(/'/g) ?? []).length;
                 const doubleQuotes = (before.match(/"/g) ?? []).length;
                 const backticks = (before.match(/`/g) ?? []).length;
-                // Se número ímpar de aspas, está dentro de string
                 const dentroDeString = singleQuotes % 2 !== 0 || doubleQuotes % 2 !== 0 || backticks % 2 !== 0;
                 if (!dentroDeString) {
                     problemas.push({
@@ -167,20 +143,11 @@ function detectarPadroesDocumentacao(src, problemas, relPath) {
             }
         }
     });
-    // [BIBLIOTECA] DETECÇÃO INTELIGENTE DE FALTA DE DOCUMENTAÇÃO
-    // Apenas reportar se:
-    // 1. É arquivo de biblioteca pública (shared/, core/, lib/) E
-    // 2. Tem exportações públicas E
-    // 3. Não tem nenhum JSDoc E
-    // 4. Não é arquivo de teste/config/setup
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- vars mutated inside forEach closure; TS can't track
     if (isLibraryArquivo && temExportacaoPublica && !temJSDoc && !isInternalArquivo && src.length > 200) {
-        // Arquivo grande o suficiente para justificar documentação
         problemas.push({
             tipo: 'missing-jsdoc',
             descricao: 'Arquivo de biblioteca pública sem documentação',
             prioridade: 'media',
-            // Reduzido de 'alta' para 'media'
             linha: 1,
             coluna: 1,
             contexto: 'Arquivo de biblioteca',
@@ -191,15 +158,12 @@ function detectarPadroesDocumentacao(src, problemas, relPath) {
 function detectarProblemasDocumentacaoAST(ast, problemas) {
     try {
         ast.traverse({
-            // [ALVO] FILOSOFIA: Detectar apenas exports DEFAULT sem JSDoc
-            // Exports nomeados podem ser auto-explicativos pelo nome
             ExportDefaultDeclaration(path) {
                 if ((path.node.declaration.type === 'FunctionDeclaration' || path.node.declaration.type === 'ClassDeclaration') && !path.node.leadingComments?.some(elem => elem.value.startsWith('*'))) {
                     problemas.push({
                         tipo: 'missing-jsdoc',
                         descricao: 'Export default (principal) sem JSDoc',
                         prioridade: 'media',
-                        // Reduzido de 'alta'
                         linha: path.node.loc?.start.line ?? 0,
                         coluna: path.node.loc?.start.column ?? 0,
                         contexto: 'Export default',
@@ -207,13 +171,10 @@ function detectarProblemasDocumentacaoAST(ast, problemas) {
                     });
                 }
             },
-            // Classes públicas complexas (>3 métodos) sem documentação
             ClassDeclaration(path) {
                 const node = path.node;
                 if (node.body.body.length > 3 &&
-                    // Apenas classes não-triviais
                     !node.leadingComments?.some(elem => elem.value.startsWith('*')) && node.id?.name && !node.id.name.toLowerCase().includes('test') && !node.id.name.toLowerCase().includes('mock')) {
-                    // Verificar se é exportada
                     const parent = path.parent;
                     const isExported = parent.type === 'ExportNamedDeclaration' || parent.type === 'ExportDefaultDeclaration';
                     if (isExported) {
@@ -229,13 +190,9 @@ function detectarProblemasDocumentacaoAST(ast, problemas) {
                     }
                 }
             }
-            // [NO] REMOVIDO: Detecção de funções com muitos parâmetros
-            // Motivo: Gera muito ruído em código interno/utils
-            // Alternativa: Revisar code review manual ou usar linter específico
         });
     }
     catch {
-        // Ignorar erros de traverse
     }
 }
 function agruparPorPrioridade(problemas) {
@@ -252,7 +209,6 @@ function mapearPrioridadeParaNivel(prioridade) {
     switch (prioridade) {
         case 'alta':
             return 'aviso';
-        // Documentação raramente é erro crítico
         case 'media':
             return 'aviso';
         case 'baixa':

package/dist/analysts/plugins/detector-markdown.js

@@ -1,66 +1,33 @@
-// @mahoraga-disable ml-deep-nesting
-// SPDX-License-Identifier: MIT
-/**
- * @fileoverview Detector de problemas em arquivos Markdown
- *
- * Verifica compliance de licenças, proveniência e referências em documentação.
- * Migrado de: scripts/scan-markdown.mjs
- * Data: 2025-11-02
- *
- * Funcionalidades:
- * - Detecta licenças incompatíveis (GPL, AGPL, CC-BY, etc)
- * - Verifica presença de aviso de proveniência
- * - Identifica referências de risco (Stack Overflow, cessão de direitos)
- * - Whitelist configurável para documentos de política
- */
 import { config } from '../../core/config/index.js';
 import { getMessages } from '../../core/messages/index.js';
 import { extrairSupressoes, isRegraSuprimida } from '../../shared/helpers/index.js';
 const { log } = getMessages();
-/**
- * Padrões de licenças e cessões problemáticas
- */
 const LICENCA_PADROES = {
     incompativeis: [/\bGPL\b/i, /\bAGPL\b/i, /\bLGPL\b/i, /Creative\s+Commons/i, /\bCC-BY\b/i, /All\s+rights\s+reserved/i],
     cessaoDireitos: [/cess(?:ã|a)o\s+de\s+direitos/i, /transfer(?:ê|e)ncia\s+de\s+direitos/i],
     referenciasRisco: [/Stack\s*Overflow/i, /(?:^|https?:\/\/|\/\/)(?:[^\/\s@]+\.)?stackoverflow\.com(?::\d+)?(?:[\/?#]|$)/i, /\bassign\b/i, /\bcession\b/i]
 };
-/**
- * Whitelist padrão de arquivos
- */
 const PADRAO_LISTA_BRANCA = {
     paths: ['.github/copilot-instructions.md', 'docs/POLICY-PROVENIENCIA.md', 'docs/partials/AVISO-PROVENIENCIA.md'],
     patterns: ['**/reports/**', 'docs/history/**', 'tests/**', 'tmp*.md'],
     dirs: ['pre-public', 'preview-mahoraga', '.abandonados', '.deprecados', 'reports']
 };
-/**
- * Cria regex combinado de todos os padrões de risco
- */
 function createRiskRegex() {
     const allPadroes = [...LICENCA_PADROES.incompativeis, ...LICENCA_PADROES.cessaoDireitos, ...LICENCA_PADROES.referenciasRisco].map(raiz => raiz.source).join('|');
     return new RegExp(allPadroes, 'i');
 }
-/**
- * Verifica se arquivo tem aviso de proveniência
- */
 function hasProvenienciaHeader(content, headerLines = 30) {
     const head = content.split(/\r?\n/).slice(0, headerLines).join('\n');
     return /Proveni[eê]ncia\s+e\s+Autoria/i.test(head);
 }
-/**
- * Verifica se arquivo está na whitelist
- */
 function isWhitelisted(relPath, whitelist) {
     const normalized = relPath.replace(/\\/g, '/');
-    // Paths exatos
     if (whitelist.paths.some((caminho) => normalized === caminho || normalized.endsWith(`/${caminho}`))) {
         return true;
     }
-    // Diretórios
     if (whitelist.dirs.some((dir) => normalized.startsWith(`${dir}/`))) {
         return true;
     }
-    // Patterns (simplificado - sem glob completo)
     for (const pattern of whitelist.patterns) {
         if (pattern.includes('**')) {
             const parts = pattern.split('**');
@@ -82,16 +49,10 @@ function isWhitelisted(relPath, whitelist) {
     }
     return false;
 }
-/**
- * Verifica se tem marcador de risco aprovado
- */
 function hasRiskReferenceMarker(content) {
     return /<!--\s*RISCO_REFERENCIA_OK\s*-->/i.test(content);
 }
 function hasMahoragaIgnoreMarker(content, key) {
-    // Suporta ambos os padrões:
-    // <!-- mahoraga-ignore: license-check -->
-    // <!-- @mahoraga-disable license-check -->
     const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const oldPattern = new RegExp(`<!--\\s*mahoraga-ignore\\s*:\\s*${escaped}\\s*-->`, 'i');
     const newPattern = new RegExp(`<!--\\s*@mahoraga-disable\\s+${escaped}(?:\\s|-->|$)`, 'i');
@@ -116,9 +77,6 @@ function mergeWhitelist(base, override, mode) {
         dirs: uniq([...base.dirs, ...overrideDirs])
     };
 }
-/**
- * Verifica se o único termo de risco é do aviso de proveniência
- */
 function isBenignProvenienciaOnly(content) {
     const rxCessao = /cess(?:ã|a)o\s+de\s+direitos/i;
     const rxOthers = new RegExp(['\\bGPL\\b', '\\bAGPL\\b', '\\bLGPL\\b', 'Creative\\s+Commons', '\\bCC-BY\\b', 'Stack\\s*Overflow', '(?:^|[^\\w.-])(?:[\\w-]+\\.)*stackoverflow\\.com(?:$|[^\\w.-])', 'All\\s+rights\\s+reserved', 'transfer(?:ê|e)ncia\\s+de\\s+direitos', '\\bassign\\b', '\\bcession\\b'].join('|'), 'i');
@@ -127,9 +85,6 @@ function isBenignProvenienciaOnly(content) {
     const hasAviso = /Proveni[eê]ncia\s+e\s+Autoria/i.test(content);
     return hasAviso && hasCessao && !hasOthers;
 }
-/**
- * Analisa um arquivo Markdown
- */
 function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
     const whitelist = options.whitelist ?? PADRAO_LISTA_BRANCA;
     const problemas = [];
@@ -137,7 +92,6 @@ function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
     const temRiscoOk = hasRiskReferenceMarker(content);
     const temProveniencia = hasProvenienciaHeader(content, options.headerLines ?? 30);
     const ignoreLicencaCheck = hasMahoragaIgnoreMarker(content, 'license-check');
-    // Verificar proveniência
     if (options.checkProveniencia !== false && !temProveniencia && !whitelisted) {
         problemas.push({
             tipo: 'falta-proveniencia',
@@ -146,18 +100,15 @@ function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
             sugestao: 'Adicione o aviso usando scripts/add-disclaimer-md.js'
         });
     }
-    // Verificar licenças e referências
     if (options.checkLicenses !== false || options.checkReferences !== false) {
         const riskRegex = createRiskRegex();
         const hasRisk = riskRegex.test(content);
         if (hasRisk && !isBenignProvenienciaOnly(content) && !whitelisted && !temRiscoOk) {
-            // Identificar problemas específicos
             const lines = content.split(/\r?\n/);
             const supressoes = extrairSupressoes(content);
             for (let indice = 0; indice < lines.length; indice++) {
                 const line = lines[indice];
                 const linhaAtual = indice + 1;
-                // Verificar licenças incompatíveis
                 if (options.checkLicenses !== false && !ignoreLicencaCheck) {
                     for (const pattern of LICENCA_PADROES.incompativeis) {
                         if (pattern.test(line)) {
@@ -175,7 +126,6 @@ function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
                         }
                     }
                 }
-                // Verificar cessão de direitos
                 if (options.checkReferences !== false) {
                     for (const pattern of LICENCA_PADROES.cessaoDireitos) {
                         if (pattern.test(line)) {
@@ -192,7 +142,6 @@ function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
                             }
                         }
                     }
-                    // Verificar referências externas
                     for (const pattern of LICENCA_PADROES.referenciasRisco) {
                         if (pattern.test(line)) {
                             const regraNome = `markdown-referencia-risco`;
@@ -221,9 +170,6 @@ function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
         temRiscoOk
     };
 }
-/**
- * Converte análise para ocorrências do Mahoraga
- */
 function converterParaOcorrencias(analise) {
     const ocorrencias = [];
     for (const problema of analise.problemas) {
@@ -254,9 +200,6 @@ function converterParaOcorrencias(analise) {
     }
     return ocorrencias;
 }
-/**
- * Detector de problemas em Markdown
- */
 export const detectorMarkdown = {
     nome: 'detector-markdown',
     categoria: 'documentacao',
@@ -288,7 +231,4 @@ export const detectorMarkdown = {
         }
     }
 };
-/**
- * Exporta função de análise standalone para uso em outros módulos
- */
 export { analisarArquivoMarkdown };

package/dist/analysts/plugins/detector-node.js

@@ -1,10 +1,5 @@
-// SPDX-License-Identifier: MIT
 import { scoreArquetipo } from '../scorers/index.js';
 import { ARQUETIPOS } from '../strategists/index.js';
-/**
- * Detector especializado para projetos Node.js/TypeScript
- * Retorna lista de candidatos de arquétipo com score/confiança
- */
 export function detectarArquetipoNode(arquivos) {
     const temPackage = arquivos.some(arquivo => arquivo.endsWith('package.json'));
     const ehNode = temPackage;

package/dist/analysts/plugins/index.js

@@ -1,24 +1,4 @@
-// SPDX-License-Identifier: MIT
-/**
- * [PLUGIN] Plugins do Mahoraga
- *
- * Analistas e detectores especializados que podem ser habilitados/desabilitados.
- * São opcionais e carregados dinamicamente pelo registry.
- *
- * Plugins Genéricos:
- * - analista-formater.ts    - Formatação mínima (JSON/MD/YAML)
- *
- * Detectores Especializados (cross-cutting):
- * - detector-documentacao.ts     - Qualidade de documentação
- * - detector-markdown.ts         - Análise de Markdown
- * - detector-node.ts             - Padrões Node.js
- *
- * Nota: Analistas específicos de tecnologia foram movidos para suas respectivas pastas:
- * - react/, python/, css/, html/, sql/, tailwind/, xml/, css-in-js/, github-actions/, shell/, svg/
- */
-// Analista genérico
 export * from './analyst-formatter.js';
-// Detectores especializados
 export * from './detector-documentation.js';
 export * from './detector-markdown.js';
 export * from './detector-node.js';

package/dist/analysts/python/analysts/analyst-python.js

@@ -1,9 +1,7 @@
-// @mahoraga-disable ml-deep-nesting
-// SPDX-License-Identifier: MIT
 import { messages } from '../../../core/messages/index.js';
 import { createLineLookup, maskPythonComments, maskPythonStringsAndComments, splitLines } from '../../../shared/helpers/index.js';
 import { criarAnalista, criarOcorrencia } from '../../../types/index.js';
-const disableEnv = process.env.SUKUNA_DISABLE_PLUGIN_PYTHON === '1';
+const disableEnv = process.env.MAHORAGA_DISABLE_PLUGIN_PYTHON === '1';
 const PYTHON_BUILTINS = new Set([
     'abs', 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable', 'chr',
     'classmethod', 'compile', 'complex', 'delattr', 'dict', 'dir', 'divmod', 'enumerate',
@@ -34,7 +32,6 @@ export function collectPythonIssues(src, relPath) {
     const scanNoComentarios = maskPythonComments(src);
     const linhas = splitLines(src);
     const isTestFile = /test/i.test(relPath);
-    // ─── Type Hints & Code Quality ────────────────────────────────
     for (const match of scan.matchAll(/^\s*(?:async\s+)?def\s+([a-z_][a-z0-9_]*)\s*\((.*?)\)(?!\s*->)/gm)) {
         const funcNome = match[1] || '';
         const line = lineOf(match.index);
@@ -43,7 +40,6 @@ export function collectPythonIssues(src, relPath) {
         }
         ocorrencias.push(warn(messages.PythonMensagens.missingTypeHints, relPath, line));
     }
-    // ─── Security Issues ──────────────────────────────────────────
     for (const match of scan.matchAll(/^\s*print\s*\(/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.printInsteadOfLog, relPath, line));
@@ -93,7 +89,6 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.sqlInjection, relPath, line, messages.SeverityNiveis.error));
     }
-    // assert in non-test code
     for (const match of scan.matchAll(/^\s*assert\s+/gm)) {
         if (isTestFile) {
             continue;
@@ -101,12 +96,10 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.assertUsage, relPath, line, messages.SeverityNiveis.warning));
     }
-    // Insecure hash algorithms
     for (const match of scan.matchAll(/\bhashlib\.(?:md5|sha1)\s*\(/gi)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.insecureHashLib, relPath, line, messages.SeverityNiveis.warning));
     }
-    // HTTP requests without timeout
     for (const match of scanNoComentarios.matchAll(/(?:requests|httpx|aiohttp)\.(?:get|post|put|delete|patch|request)\s*\([^)]*\)/g)) {
         if (/\btimeout\s*=/.test(match[0])) {
             continue;
@@ -114,12 +107,10 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.requestWithoutTimeout, relPath, line, messages.SeverityNiveis.warning));
     }
-    // Insecure temporary file creation
     for (const match of scan.matchAll(/\btempfile\.mktemp\s*\(/gi)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.tempfileSecurity, relPath, line, messages.SeverityNiveis.error));
     }
-    // ─── Exception Handling ───────────────────────────────────────
     for (const match of scan.matchAll(/^\s*except\s*:\s*$/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.broadExcept, relPath, line));
@@ -132,7 +123,6 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.bareRaise, relPath, line));
     }
-    // except blocks without logging the exception
     for (const match of src.matchAll(/except\s+(\w+)\s+as\s+(\w+)\s*:((?:[ \t]+.*\n?)*?)(?=\n\S|\n\s*(?:except|else|finally|def|class)|$)/gm)) {
         const excVar = match[2];
         const block = match[3];
@@ -146,7 +136,6 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.loggingWithoutException, relPath, line, messages.SeverityNiveis.warning));
     }
-    // ─── Code Quality & Best Practices ────────────────────────────
     for (const match of scan.matchAll(/^\s*global\s+\w+/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.globalKeyword, relPath, line));
@@ -155,7 +144,6 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.mutableDefault, relPath, line));
     }
-    // Check for typing imports missing
     const hasTypingImport = /^from\s+typing\s+import/m.test(src);
     if (!hasTypingImport) {
         const typingTypes = /\b(List|Dict|Optional|Union|Tuple|Set|FrozenSet|Callable|Iterable|Iterator|Generator|TypeVar|Any|Mapping|Sequence)\b/g;
@@ -164,24 +152,20 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.typingImportMissing, relPath, line, messages.SeverityNiveis.suggestion));
         }
     }
-    // Wildcard imports
     for (const match of scan.matchAll(/^from\s+[\w.]+\s+import\s+\*/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.wildcardImport, relPath, line, messages.SeverityNiveis.warning));
     }
-    // Deep relative imports (3+ dots)
     for (const match of scan.matchAll(/^from\s+\.{3,}\w/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.relativeImportDeep, relPath, line, messages.SeverityNiveis.info));
     }
-    // Long lines
     linhas.forEach((linha, idx) => {
         const line = idx + 1;
         if (linha.length > 79 && !/^\s*#/.test(linha)) {
             ocorrencias.push(warn(messages.PythonMensagens.longLine, relPath, line, messages.SeverityNiveis.info));
         }
     });
-    // Variables shadowing built-in names
     const varAssignmentPattern = /(?:^|\s)([a-z_][a-z0-9_]*)\s*=\s*(?![=<>!])/gm;
     for (const match of scan.matchAll(varAssignmentPattern)) {
         const varName = match[1];
@@ -190,12 +174,10 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.shadowBuiltin, relPath, line, messages.SeverityNiveis.info));
         }
     }
-    // Task/FIXME comments (on original src, before masking)
     for (const match of src.matchAll(/#\s*(TODO|FIXME|HACK|XXX|BUG|WORKAROUND)[:\s]/gi)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.todoFixme, relPath, line, messages.SeverityNiveis.info));
     }
-    // Commented-out code lines
     for (let i = 0; i < linhas.length; i++) {
         const trimmed = linhas[i].trim();
         const codePattern = /^#\s*(?:if|for|while|def|class|return|import|from|print|self\.|with|try|except|elif|else)\s+/;
@@ -203,12 +185,10 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.commentedCode, relPath, i + 1, messages.SeverityNiveis.info));
         }
     }
-    // Return outside function (module-level return)
     for (const match of scan.matchAll(/^return\b/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.returnOutsideFunction, relPath, line, messages.SeverityNiveis.error));
     }
-    // Unused variable (simple heuristic: variable assigned but never referenced in same function)
     const funcBodies = src.matchAll(/(?:^|\n)((?:    |\t)*(?:async\s+)?def\s+\w+\s*\([^)]*\)\s*:\s*\n((?:\1(?:    |\t).*(?:\n|$))*))/gm);
     for (const funcMatch of funcBodies) {
         const funcBody = funcMatch[2] || '';
@@ -240,8 +220,6 @@ export function collectPythonIssues(src, relPath) {
             }
         }
     }
-    // ─── Complexidade ─────────────────────────────────────────────
-    // Too many return statements in a function
     for (const funcMatch of src.matchAll(/(^|\n)((?:    |\t)*(?:async\s+)?def\s+(\w+)\s*\([^)]*\)\s*:\s*\n((?:\1(?:    |\t).*(?:\n|$))*))/gm)) {
         const funcBody = funcMatch[3] || '';
         const funcName = funcMatch[2] || '';
@@ -254,7 +232,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.tooManyReturns, relPath, line, messages.SeverityNiveis.info));
         }
     }
-    // Too many branches (if/elif/else) in a function
     for (const funcMatch of src.matchAll(/(^|\n)((?:    |\t)*(?:async\s+)?def\s+\w+\s*\([^)]*\)\s*:\s*\n((?:\1(?:    |\t).*(?:\n|$))*))/gm)) {
         const funcBody = funcMatch[3] || '';
         const branchCount = (funcBody.match(/\b(?:if|elif|else)\b/g) ?? []).length;
@@ -263,7 +240,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.tooManyBranches, relPath, line, messages.SeverityNiveis.info));
         }
     }
-    // ─── Performance & Design ─────────────────────────────────────
     for (const match of scan.matchAll(/for\s+\w+\s+in\s+\w+:\s*\n\s*(\w+)\.append\s*\(/g)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.listComprehensionOpportunity, relPath, line, messages.SeverityNiveis.suggestion));
@@ -272,12 +248,10 @@ export function collectPythonIssues(src, relPath) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.loopingOverDict, relPath, line, messages.SeverityNiveis.suggestion));
     }
-    // Iterating dict without .items() in complex context (multi-line)
     for (const match of scan.matchAll(/for\s+(\w+)\s+in\s+(\w+):\s*\n(?:\s+.*\n)*?\s+\1\[/gm)) {
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.dictIteration, relPath, line, messages.SeverityNiveis.suggestion));
     }
-    // Loop variable overwritten in loop body
     for (const match of scan.matchAll(/for\s+(\w+)\s+in\s+.+:\s*\n((?:\s+.*\n)*?)/g)) {
         const loopVar = match[1];
         const body = match[2] || '';
@@ -287,7 +261,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.redefinedLoopVar, relPath, line, messages.SeverityNiveis.info));
         }
     }
-    // Class could be a dataclass
     for (const match of src.matchAll(/^class\s+(\w+)[\s\S]*?^\s+def\s+__init__\s*\(self\s*,\s*([^)]*)\)\s*:\s*\n((?:\s+.*\n)*?)(?=\n\S|\nclass |$)/gm)) {
         const initBody = match[3] || '';
         const params = (match[2] || '').split(',').map(p => p.trim().split('=')[0].trim()).filter(p => p && p !== 'self');
@@ -304,7 +277,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.dataclassOpportunity, relPath, line, messages.SeverityNiveis.suggestion));
         }
     }
-    // Consider Enum for string constants group
     for (const match of src.matchAll(/^class\s+(\w+)[\s\S]*?((?:^\s+\w+\s*=\s*['"][^'"]*['"]\s*$\n?)+)/gm)) {
         const constantsBlock = match[2] || '';
         const constLines = constantsBlock.trim().split('\n').filter(l => /^\s+\w+\s*=/.test(l));
@@ -314,7 +286,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.considerEnum, relPath, line, messages.SeverityNiveis.suggestion));
         }
     }
-    // Async function without await
     for (const match of src.matchAll(/^\s*async\s+def\s+(\w+)\s*\([^)]*\)\s*:\s*\n((?:(?:\s+.*\n?)*?)(?=\n\S|\n\s*async\s+def|\n\s*def\s+|\nclass |$))/gm)) {
         const body = match[2] || '';
         if (!/\bawait\b/.test(body)) {
@@ -322,7 +293,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.asyncWithoutAwait, relPath, line, messages.SeverityNiveis.warning));
         }
     }
-    // f-string without expression (wasted computation)
     for (const match of scan.matchAll(/f(['"])(?:\\[^]|[^\\])*?\1/g)) {
         const fstr = match[0];
         if (!/\{[^}]+\}/.test(fstr)) {
@@ -330,7 +300,6 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.fstringWithoutExpression, relPath, line, messages.SeverityNiveis.info));
         }
     }
-    // ─── Django-specific (lightweight) ────────────────────────────
     if (/django/i.test(relPath) || /settings\.py$/.test(relPath)) {
         for (const match of scan.matchAll(/SECRET_KEY\s*=\s*['"][^'"]+['"]/g)) {
             const val = match[0];