@mocoto/mahoraga 0.14.0 → 0.14.2

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

@@ -1,33 +1,65 @@
+// 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('**');
@@ -49,22 +81,28 @@ 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');
     return oldPattern.test(content) || newPattern.test(content);
 }
 function mergeWhitelist(base, override, mode) {
-    const overrideConfig = override || {};
+    const overrideConfig = override ?? {};
     if (mode === 'replace') {
         return {
-            paths: Array.isArray(overrideConfig.paths) ? overrideConfig.paths : [],
-            patterns: Array.isArray(overrideConfig.patterns) ? overrideConfig.patterns : [],
-            dirs: Array.isArray(overrideConfig.dirs) ? overrideConfig.dirs : []
+            paths: overrideConfig.paths ?? [],
+            patterns: overrideConfig.patterns ?? [],
+            dirs: overrideConfig.dirs ?? []
         };
     }
     const uniq = (arr) => Array.from(new Set(arr.map(String)));
@@ -72,11 +110,14 @@ function mergeWhitelist(base, override, mode) {
     const overridePatterns = Array.isArray(overrideConfig.patterns) ? overrideConfig.patterns : [];
     const overrideDirs = Array.isArray(overrideConfig.dirs) ? overrideConfig.dirs : [];
     return {
-        paths: uniq([...(base.paths || []), ...overridePaths]),
-        patterns: uniq([...(base.patterns || []), ...overridePatterns]),
-        dirs: uniq([...(base.dirs || []), ...overrideDirs])
+        paths: uniq([...base.paths, ...overridePaths]),
+        patterns: uniq([...base.patterns, ...overridePatterns]),
+        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');
@@ -85,13 +126,17 @@ function isBenignProvenienciaOnly(content) {
     const hasAviso = /Proveni[eê]ncia\s+e\s+Autoria/i.test(content);
     return hasAviso && hasCessao && !hasOthers;
 }
-async function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
-    const whitelist = options.whitelist || PADRAO_LISTA_BRANCA;
+/**
+ * Analisa um arquivo Markdown
+ */
+function analisarArquivoMarkdown(fullCaminho, relPath, content, options) {
+    const whitelist = options.whitelist ?? PADRAO_LISTA_BRANCA;
     const problemas = [];
     const whitelisted = isWhitelisted(relPath, whitelist);
     const temRiscoOk = hasRiskReferenceMarker(content);
-    const temProveniencia = hasProvenienciaHeader(content, options.headerLines || 30);
+    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',
@@ -100,15 +145,18 @@ async 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)) {
@@ -126,6 +174,7 @@ async 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)) {
@@ -142,6 +191,7 @@ async 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`;
@@ -170,6 +220,9 @@ async 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) {
@@ -182,6 +235,9 @@ function converterParaOcorrencias(analise) {
             case 'medio':
                 nivel = 'aviso';
                 break;
+            case "baixo": {
+                throw new Error('Not implemented yet: "baixo" case');
+            }
             default:
                 nivel = 'info';
         }
@@ -197,6 +253,9 @@ function converterParaOcorrencias(analise) {
     }
     return ocorrencias;
 }
+/**
+ * Detector de problemas em Markdown
+ */
 export const detectorMarkdown = {
     nome: 'detector-markdown',
     categoria: 'documentacao',
@@ -204,7 +263,7 @@ export const detectorMarkdown = {
     test: (relPath) => {
         return relPath.toLowerCase().endsWith('.md');
     },
-    aplicar: async (src, relPath, _ast, fullCaminho) => {
+    aplicar: (src, relPath, _ast, fullCaminho) => {
         if (!fullCaminho) {
             log.aviso(getMessages().LicensasMensagens.detectorMarkdownPath.replace('{arquivo}', relPath));
             return [];
@@ -219,7 +278,7 @@ export const detectorMarkdown = {
             whitelist: mergeWhitelist(PADRAO_LISTA_BRANCA, cfg?.whitelist, whitelistMode)
         };
         try {
-            const analise = await analisarArquivoMarkdown(fullCaminho, relPath, src, options);
+            const analise = analisarArquivoMarkdown(fullCaminho, relPath, src, options);
             return converterParaOcorrencias(analise);
         }
         catch (error) {
@@ -228,5 +287,7 @@ export const detectorMarkdown = {
         }
     }
 };
+/**
+ * Exporta função de análise standalone para uso em outros módulos
+ */
 export { analisarArquivoMarkdown };
-//# sourceMappingURL=detector-markdown.js.map

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

@@ -1,11 +1,16 @@
+// 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;
-    if (!ehNode)
+    if (!ehNode) {
         return [];
+    }
     const candidatos = ARQUETIPOS.map(def => scoreArquetipo(def, arquivos)).filter(raiz => raiz.score > 0);
     return candidatos;
 }
-//# sourceMappingURL=detector-node.js.map

package/dist/analysts/plugins/index.js

@@ -1,5 +1,24 @@
+// 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';
-//# sourceMappingURL=index.js.map

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

@@ -1,7 +1,8 @@
+// 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.MAHORAGA_DISABLE_PLUGIN_PYTHON === '1';
+const disableEnv = process.env.SUKUNA_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',
@@ -32,13 +33,16 @@ 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);
-        if (/^__|main|__init__|setUp|tearDown|get_|set_/.test(funcNome))
+        if (/^__|main|__init__|setUp|tearDown|get_|set_/.test(funcNome)) {
             continue;
+        }
         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));
@@ -52,8 +56,9 @@ export function collectPythonIssues(src, relPath) {
         ocorrencias.push(warn(messages.PythonMensagens.execUsage, relPath, line, messages.SeverityNiveis.error));
     }
     for (const match of scan.matchAll(/\bsubprocess\.(?:run|Popen|call|check_call|check_output)\s*\([\s\S]*?\)/g)) {
-        if (!/\bshell\s*=\s*True\b/.test(match[0]))
+        if (!/\bshell\s*=\s*True\b/.test(match[0])) {
             continue;
+        }
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.subprocessShellTrue, relPath, line, messages.SeverityNiveis.error));
     }
@@ -62,12 +67,13 @@ export function collectPythonIssues(src, relPath) {
         ocorrencias.push(warn(messages.PythonMensagens.pickleUsage, relPath, line, messages.SeverityNiveis.error));
     }
     for (const match of scan.matchAll(/\byaml\.load\s*\([\s\S]*?\)/gi)) {
-        const text = match[0] ?? '';
+        const text = match[0];
         const hasSafeLoader = /\bLoader\s*=\s*yaml\.(?:SafeLoader|CSafeLoader)\b/.test(text);
         const hasFullLoader = /\bLoader\s*=\s*yaml\.(?:FullLoader|CFullLoader)\b/.test(text);
         const hasExplicitLoader = /\bLoader\s*=/.test(text);
-        if (hasSafeLoader)
+        if (hasSafeLoader) {
             continue;
+        }
         const line = lineOf(match.index);
         ocorrencias.push(warn(messages.PythonMensagens.yamlUnsafeLoad, relPath, line, hasFullLoader || hasExplicitLoader ? messages.SeverityNiveis.warning : messages.SeverityNiveis.error));
     }
@@ -79,32 +85,40 @@ export function collectPythonIssues(src, relPath) {
         }
     }
     for (const match of scanNoComentarios.matchAll(/\b(?:execute|executemany|executescript)\s*\(\s*f(['"])(?:SELECT|INSERT|UPDATE|DELETE)[\s\S]*?\1/gi)) {
-        const text = match[0] ?? '';
-        if (!/\{[^}]+\}/.test(text))
+        const text = match[0];
+        if (!/\{[^}]+\}/.test(text)) {
             continue;
+        }
         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)
+        if (isTestFile) {
             continue;
+        }
         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]))
+        if (/\btimeout\s*=/.test(match[0])) {
             continue;
+        }
         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));
@@ -117,19 +131,21 @@ 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)) {
-        if (match[3] === undefined)
-            continue;
         const excVar = match[2];
         const block = match[3];
-        if (!block || block.trim() === '' || block.trim() === 'pass')
+        if (!block || block.trim() === '' || block.trim() === 'pass') {
             continue;
+        }
         const loggingPattern = new RegExp(`\\\\b(logging\\\\.|traceback\\\\.|print\\\\s*\\\\(.*\\\\b${excVar}\\\\b)`);
-        if (loggingPattern.test(block))
+        if (loggingPattern.test(block)) {
             continue;
+        }
         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));
@@ -138,6 +154,7 @@ 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;
@@ -146,20 +163,24 @@ 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];
@@ -168,10 +189,12 @@ export function collectPythonIssues(src, relPath) {
             ocorrencias.push(warn(messages.PythonMensagens.shadowBuiltin, relPath, line, messages.SeverityNiveis.info));
         }
     }
+    // TODO/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+/;
@@ -179,10 +202,12 @@ 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] || '';
@@ -198,38 +223,46 @@ export function collectPythonIssues(src, relPath) {
             referenced.add(m[1]);
         }
         for (const v of assigned) {
-            if (v.startsWith('_'))
+            if (v.startsWith('_')) {
                 continue;
-            if (!referenced.has(v) || (funcBody.match(new RegExp(`\\b${v}\\b`, 'g')) || []).length <= 1) {
-                if (funcBody.includes(`def ${v}`) || funcBody.includes(`class ${v}`))
+            }
+            if (!referenced.has(v) || (funcBody.match(new RegExp(`\\b${v}\\b`, 'g')) ?? []).length <= 1) {
+                if (funcBody.includes(`def ${v}`) || funcBody.includes(`class ${v}`)) {
                     continue;
+                }
                 const pos = funcBody.indexOf(`${v}=`);
-                if (pos === -1)
+                if (pos === -1) {
                     continue;
+                }
                 const absLine = lineOf(funcMatch.index + pos + 1);
                 ocorrencias.push(warn(messages.PythonMensagens.unusedVariable, relPath, absLine, messages.SeverityNiveis.info));
             }
         }
     }
+    // ─── 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] || '';
-        if (/^__/.test(funcName))
+        if (/^__/.test(funcName)) {
             continue;
-        const returnCount = (funcBody.match(/\breturn\b/g) || []).length;
+        }
+        const returnCount = (funcBody.match(/\breturn\b/g) ?? []).length;
         if (returnCount >= 5) {
             const line = lineOf(funcMatch.index + 1);
             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;
+        const branchCount = (funcBody.match(/\b(?:if|elif|else)\b/g) ?? []).length;
         if (branchCount >= 10) {
             const line = lineOf(funcMatch.index + 1);
             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));
@@ -238,10 +271,12 @@ 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] || '';
@@ -251,14 +286,16 @@ 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');
         const assignedInInit = new Set();
         for (const line of initBody.split('\n')) {
             const assignMatch = line.match(/^\s+self\.(\w+)\s*=\s*/);
-            if (assignMatch)
+            if (assignMatch) {
                 assignedInInit.add(assignMatch[1]);
+            }
         }
         const allSelfAssigns = params.every(p => assignedInInit.has(p));
         if (allSelfAssigns && params.length >= 2 && !/@dataclass/.test(src.slice(Math.max(0, match.index - 100), match.index))) {
@@ -266,6 +303,7 @@ 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));
@@ -275,6 +313,7 @@ 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)) {
@@ -282,6 +321,7 @@ 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)) {
@@ -289,6 +329,7 @@ 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];
@@ -319,13 +360,14 @@ export const analistaPython = criarAnalista({
     descricao: 'Heurísticas leves para Python (boas práticas e segurança).',
     global: false,
     test: (relPath) => isPythonFile(relPath),
-    aplicar: async (src, relPath) => {
-        if (disableEnv)
+    aplicar: (src, relPath) => {
+        if (disableEnv) {
             return null;
-        if (relPath.includes('src/analistas/plugins/analista-python.ts'))
+        }
+        if (relPath.includes('src/analistas/plugins/analista-python.ts')) {
             return null;
+        }
         const msgs = collectPythonIssues(src, relPath);
         return msgs.length ? msgs : null;
     }
 });
-//# sourceMappingURL=analyst-python.js.map

package/dist/analysts/python/analysts/index.js

@@ -1,2 +1 @@
 export * from './analyst-python.js';
-//# sourceMappingURL=index.js.map

package/dist/analysts/python/corrections/correction-python.js

@@ -1,3 +1,12 @@
+// SPDX-License-Identifier: MIT
+/**
+ * [CHAVE-INGLESA] Correções automáticas para Python
+ *
+ * Fornece correções sugeridas para problemas comuns em Python:
+ * - Bare except → except Exception
+ * - Mutable defaults → None pattern
+ * - print → logging
+ */
 import { messages } from '../../../core/messages/index.js';
 import { maskPythonComments, splitLines } from '../../../shared/helpers/index.js';
 import { criarOcorrencia } from '../../../types/index.js';
@@ -46,8 +55,9 @@ export const correctionPython = {
     descricao: 'Correções automáticas para problemas Python',
     test: (relPath) => /\.(py|pyx|pyi)$/i.test(relPath),
     aplicar: (src, relPath) => {
-        if (!src)
+        if (!src) {
             return [];
+        }
         const correcoes = detectarCorrecoesPython(src, relPath);
         return correcoes.map(elem => criarOcorrencia({
             tipo: `correction-${elem.tipo}`,
@@ -59,4 +69,3 @@ export const correctionPython = {
         }));
     }
 };
-//# sourceMappingURL=correction-python.js.map

package/dist/analysts/python/corrections/index.js

@@ -1,2 +1,2 @@
+// SPDX-License-Identifier: MIT
 export * from './correction-python.js';
-//# sourceMappingURL=index.js.map

package/dist/analysts/python/detectors/detector-python-best-practices.js

@@ -1,3 +1,10 @@
+// SPDX-License-Identifier: MIT
+/**
+ * [BUSCA] Detector de boas práticas Python
+ *
+ * Delega para o analista principal (analyst-python) e retorna
+ * as ocorrências usando mensagens centralizadas.
+ */
 import { collectPythonIssues } from '../analysts/analyst-python.js';
 export const detectorPythonBestPractices = {
     nome: 'detector-python-best-practices',
@@ -5,8 +12,9 @@ export const detectorPythonBestPractices = {
     descricao: 'Detecta más práticas em código Python (delega para analyst-python)',
     test: (relPath) => /\.(py|pyx|pyi)$/i.test(relPath),
     aplicar: (src, relPath) => {
-        if (!src)
+        if (!src) {
             return [];
+        }
         const issues = collectPythonIssues(src, relPath);
         return issues.map(i => ({
             ...i,
@@ -14,4 +22,3 @@ export const detectorPythonBestPractices = {
         }));
     }
 };
-//# sourceMappingURL=detector-python-best-practices.js.map

package/dist/analysts/python/detectors/index.js

@@ -1,2 +1,2 @@
+// SPDX-License-Identifier: MIT
 export * from './detector-python-best-practices.js';
-//# sourceMappingURL=index.js.map