@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/validators/nextjs/next-component-validator.js

@@ -2,25 +2,8 @@ import { glob } from 'glob';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-/**
- * Next.js Component Validator
- *
- * Validates .tsx files for:
- * 1. Unnecessary 'use client' directives (no interactivity)
- * 2. Missing 'use client' when React hooks are used
- * 3. File naming convention (kebab-case)
- *
- * @module next-component-validator
- */
-
-// ============================================
-// CONSTANTS
-// ============================================
-
-/** Hooks/patterns that require 'use client' */
 const CLIENT_HOOKS = ['useState', 'useEffect', 'useRef', 'useReducer', 'useCallback', 'useMemo', 'useContext'];
 
-/** Event handler patterns that indicate interactivity (hooks are checked via CLIENT_HOOKS) */
 const EVENT_HANDLER_PATTERNS = [
   /\bonClick\b/,
   /\bonChange\b/,
@@ -28,66 +11,29 @@ const EVENT_HANDLER_PATTERNS = [
   /\bonFocus\b/,
   /\bonBlur\b/,
   /\bonKeyDown\b/,
-  // Qualquer outro handler de evento em JSX (onMouseEnter, onKeyUp, onScroll, onDrop…).
-  // Sem isto, a lista fechada acima transforma interatividade legítima em falso-positivo.
   /\bon[A-Z]\w*\s*=\s*\{/,
 ];
 
-/**
- * Chamada de QUALQUER hook, não só os sete nativos: `useRouter()`, `useQuery()`, `useForm<T>()`.
- * O `[<(]` é o que faz `useState<Record<string, string>>(` contar — um hook com argumento de
- * tipo não casa com `useState\s*\(` e passava despercebido.
- */
+// `[<(]` faz hook com argumento de tipo (`useState<Record<string, string>>(`) contar.
 const HOOK_CALL_PATTERN = /\buse[A-Z]\w*\s*[<(]/;
 
-/**
- * APIs de React que só existem no cliente. `forwardRef` e `createContext` lançam em Server
- * Component, então um módulo que os usa PRECISA da diretiva, mesmo sem hook nem handler.
- */
+// Lançam em Server Component: o módulo precisa da diretiva mesmo sem hook nem handler.
 const CLIENT_ONLY_APIS = [/\bforwardRef\b/, /\bcreateContext\b/];
 
-/** Globais de browser: quem os toca não roda no servidor. */
 const BROWSER_GLOBALS = /\b(window|document|localStorage|sessionStorage|navigator)\s*[.[]/;
 
-/**
- * Pacotes cujos componentes são client-only. O caso que mais gerava ruído é o wrapper de
- * shadcn/Radix: ele só reexporta primitivas, então não tem hook nem handler no próprio
- * arquivo — e era acusado para sempre, apesar de estar correto.
- */
+// Wrapper shadcn/Radix só reexporta primitivas client-only, sem hook nem handler no arquivo.
 const CLIENT_ONLY_IMPORTS = /from\s+['"](@radix-ui\/|sonner|@react-pdf\/|file-saver|framer-motion|motion\/|recharts|next\/navigation|react-hook-form|@tanstack\/react-query|embla-carousel|cmdk|vaul|react-day-picker|input-otp|@dnd-kit\/)/;
 
-/** Next.js special files exempt from naming checks */
 const NEXTJS_SPECIAL_FILES = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx', 'route.ts', 'middleware.ts'];
 
-// ============================================
-// MAIN VALIDATION FUNCTION
-// ============================================
-
-/**
- * @typedef {Object} ValidationIssue
- * @property {'error' | 'warning' | 'info'} type
- * @property {string} message
- * @property {string} [suggestion]
- * @property {string} file
- * @property {number} [line]
- */
-
-/**
- * Validates a Next.js component file.
- *
- * @param {string} content - File content
- * @param {string} filePath - Relative file path
- * @returns {ValidationIssue[]}
- */
 export function validateNextComponent(content, filePath) {
   const issues = [];
 
-  // Only validate .tsx and .ts files
   if (!filePath.endsWith('.tsx') && !filePath.endsWith('.ts')) {
     return issues;
   }
 
-  // Skip non-component utility files (no JSX, no hooks)
   const hasJsx = /(?<![a-zA-Z0-9])<[A-Z][a-zA-Z]*[\s/>]|(?<![a-zA-Z0-9])<[a-z][a-z]+[\s>/]/.test(content);
   const hasHooks = CLIENT_HOOKS.some(hook => content.includes(hook));
 
@@ -97,13 +43,10 @@ export function validateNextComponent(content, filePath) {
 
   const hasUseClient = /^'use client';?|^"use client";?/.test(content.trimStart());
 
-  // Check 1: use client present but no interactivity
   if (hasUseClient) {
     const hasEventHandlers = EVENT_HANDLER_PATTERNS.some(pattern => pattern.test(content));
     const hasClientHooks = CLIENT_HOOKS.some(hook => new RegExp(`\\b${hook}\\b`).test(content));
-    // Só acusa quando NENHUM sinal de necessidade de cliente aparece. Um falso-positivo aqui
-    // pede a remoção de uma diretiva que o build precisa, então a checagem erra para o lado
-    // de ficar calada.
+    // Falso-positivo pediria remover uma diretiva que o build precisa: erra para o lado calado.
     const needsClient =
       hasEventHandlers ||
       hasClientHooks ||
@@ -121,7 +64,6 @@ export function validateNextComponent(content, filePath) {
     }
   }
 
-  // Check 2: hooks used without use client
   // .ts files (custom hooks, utilities) never render JSX — skip this check
   if (!hasUseClient) {
     if (!filePath.endsWith('.tsx')) return issues;
@@ -137,7 +79,6 @@ export function validateNextComponent(content, filePath) {
     }
   }
 
-  // Check 3: file naming convention (kebab-case)
   const fileName = filePath.split('/').pop() ?? '';
   const isSpecialFile = NEXTJS_SPECIAL_FILES.includes(fileName);
 
@@ -157,10 +98,6 @@ export function validateNextComponent(content, filePath) {
   return issues;
 }
 
-// ============================================
-// HELPERS
-// ============================================
-
 function toKebabCase(str) {
   return str
     .replace(/([A-Z])/g, '-$1')
@@ -168,22 +105,9 @@ function toKebabCase(str) {
     .replace(/^-/, '');
 }
 
-// ============================================
-// PROJECT-LEVEL SCANNER
-// ============================================
-
-/**
- * Validates all Next.js component files in a project directory.
- * Wraps validateNextComponent for use in validation-runner.js.
- *
- * @param {string} projectPath - Root path of the project
- * @param {Object} _options - Validator options (unused, for interface compatibility)
- * @returns {Promise<{ errors: number, warnings: number, issues: Array }>}
- */
 export async function validateNextComponentFiles(projectPath, _options = {}) {
   const result = { errors: 0, warnings: 0, issues: [] };
 
-  // Find all .tsx and .ts files under src/
   const srcDir = join(projectPath, 'src');
   const normalizedSrc = srcDir.replace(/\\/g, '/');
   const pattern = normalizedSrc + '/**/*.{tsx,ts}';
@@ -197,7 +121,6 @@ export async function validateNextComponentFiles(projectPath, _options = {}) {
       continue;
     }
 
-    // Make path relative for cleaner output
     const normFilePath = filePath.replace(/\\/g, '/');
     const relPath = normFilePath.replace(projectPath.replace(/\\/g, '/') + '/', '');
     const fileIssues = validateNextComponent(content, relPath);

package/src/lib/validators/packages/index.js

@@ -1,7 +1 @@
-/**
- * Package Validators
- *
- * Package and dependency validation.
- */
-
 export * from './package-validator.js';

package/src/lib/validators/packages/package-validator.js

@@ -1,21 +1,9 @@
-/**
- * Package Compatibility Validator
- *
- * Validates NuGet package versions against .NET compatibility matrix.
- * Critical for .NET 10 migration - prevents runtime errors.
- *
- * MORPH-SPEC 3.0 - Sprint 4
- */
-
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import { glob } from 'glob';
 import chalk from 'chalk';
 
-/**
- * Compatibility matrix for .NET versions
- * Source: framework/standards/dotnet10-compatibility.md
- */
+// Source: framework/standards/dotnet10-compatibility.md
 const COMPATIBILITY_MATRIX = {
   'Hangfire.AspNetCore': {
     9: '1.8.0',
@@ -50,7 +38,7 @@ const COMPATIBILITY_MATRIX = {
     breaking: false
   },
   'Microsoft.SemanticKernel': {
-    9: null, // Not compatible with .NET 10
+    9: null,
     10: null,
     deprecated: true,
     replacement: 'Microsoft.Extensions.AI.Abstractions',
@@ -58,17 +46,11 @@ const COMPATIBILITY_MATRIX = {
   }
 };
 
-/**
- * Package Validator Class
- */
 export class PackageValidator {
   constructor(projectPath = '.') {
     this.projectPath = projectPath;
   }
 
-  /**
-   * Validate all .csproj files in project
-   */
   async validateAll() {
     const csprojFiles = await glob('**/*.csproj', {
       cwd: this.projectPath,
@@ -86,10 +68,7 @@ export class PackageValidator {
     const allIssues = [];
 
     for (const file of csprojFiles) {
-      // glob returns paths relative to `cwd: this.projectPath`, so they only
-      // resolve against projectPath — reading them relative to process.cwd()
-      // raised ENOENT whenever the two differed (worktree, fleet, a verify
-      // launched from the primary root), and the throw read as a clean pass.
+      // glob paths are relative to `cwd: this.projectPath`, never to process.cwd().
       const result = await this.validateFile(join(this.projectPath, file));
       if (result.issues.length > 0) {
         results.push({ file, ...result });
@@ -101,9 +80,7 @@ export class PackageValidator {
       status: results.length === 0 ? 'ok' : 'error',
       totalFiles: csprojFiles.length,
       filesWithIssues: results.length,
-      // The runner's contract. Without these three the findings below were
-      // read as `errors: 0` and the run reported "✅ All validations passed"
-      // while holding a list of NuGet packages that do not build on .NET 10.
+      // The runner's contract: without these counts the findings read as `errors: 0`.
       errors: allIssues.filter(i => i.level === 'error').length,
       warnings: allIssues.filter(i => i.level === 'warning').length,
       issues: allIssues,
@@ -111,13 +88,9 @@ export class PackageValidator {
     };
   }
 
-  /**
-   * Validate single .csproj file
-   */
   async validateFile(filePath) {
     const content = readFileSync(filePath, 'utf-8');
 
-    // Extract .NET version
     const tfmMatch = content.match(/<TargetFramework>(.*?)<\/TargetFramework>/);
     if (!tfmMatch) {
       return {
@@ -142,10 +115,8 @@ export class PackageValidator {
       };
     }
 
-    // Extract package references
     const packages = this.extractPackages(content);
 
-    // Validate each package
     const issues = [];
 
     for (const pkg of packages) {
@@ -162,9 +133,6 @@ export class PackageValidator {
     };
   }
 
-  /**
-   * Extract package references from .csproj content
-   */
   extractPackages(csprojContent) {
     const packages = [];
     const packageRegex = /<PackageReference\s+Include="([^"]+)"\s+Version="([^"]+)"/g;
@@ -180,18 +148,13 @@ export class PackageValidator {
     return packages;
   }
 
-  /**
-   * Validate single package against compatibility matrix
-   */
   validatePackage(pkg, dotnetVersion) {
     const rule = COMPATIBILITY_MATRIX[pkg.name];
 
     if (!rule) {
-      // Package not in matrix - no validation
       return null;
     }
 
-    // Check if deprecated
     if (rule.deprecated) {
       return {
         level: 'error',
@@ -204,7 +167,6 @@ export class PackageValidator {
       };
     }
 
-    // Check if version is sufficient
     const requiredVersion = rule[dotnetVersion];
 
     if (!requiredVersion) {
@@ -235,13 +197,10 @@ export class PackageValidator {
       };
     }
 
-    return null; // Package is compatible
+    return null;
   }
 
-  /**
-   * Compare semantic versions
-   * Returns: -1 (v1 < v2), 0 (equal), 1 (v1 > v2)
-   */
+  // -1 (v1 < v2), 0 (equal), 1 (v1 > v2)
   compareVersions(v1, v2) {
     const parts1 = v1.split('.').map(p => parseInt(p.replace(/[^0-9]/g, '')) || 0);
     const parts2 = v2.split('.').map(p => parseInt(p.replace(/[^0-9]/g, '')) || 0);
@@ -259,9 +218,6 @@ export class PackageValidator {
     return 0;
   }
 
-  /**
-   * Format validation results for console output
-   */
   formatResults(results) {
     if (results.status === 'ok') {
       console.log(chalk.green('✅ All packages are compatible'));
@@ -314,9 +270,6 @@ export class PackageValidator {
     }
   }
 
-  /**
-   * Auto-fix compatible issues
-   */
   async autoFix(results) {
     const { execSync } = await import('child_process');
     let fixedCount = 0;
@@ -340,9 +293,6 @@ export class PackageValidator {
   }
 }
 
-/**
- * Quick validation function (for imports)
- */
 export async function validatePackages(projectPath = '.', options = {}) {
   const validator = new PackageValidator(projectPath);
   const results = await validator.validateAll();

package/src/lib/validators/reuse/index.js

@@ -1,10 +1,2 @@
-/**
- * Reuse Validators
- *
- * Cobrança determinística de reuso de código: símbolo novo cujo nome já existe
- * no grafo do codebase, na mesma linguagem. É a terceira camada do ciclo
- * PROSA → ARTEFATO → VERIFICAÇÃO (ver reuse-validator.js).
- */
-
 export * from './reuse-validator.js';
 export * from './symbol-scanner.js';

package/src/lib/validators/reuse/reuse-validator.js

@@ -1,32 +1,6 @@
-/**
- * Reuse Validator — símbolo novo cujo nome já existe no codebase.
- *
- * A terceira camada do ciclo de reuso:
- *
- *   PROSA (morph-plan, personas)  ──►  ARTEFATO (seção de reuso do plano)
- *   ──►  COBRANÇA (este arquivo)
- *
- * Prosa sozinha não segura — a skill de planejamento já mandava olhar o que
- * existe, e o ProspectPRO redefiniu `SimpleBuilding` em cinco arquivos da
- * MESMA pasta assim mesmo: só a verificação em código segura o ciclo.
- *
- * Regras, na ordem em que reduzem ruído:
- *
- *   1. Só tipo (class/record/interface/enum/struct/type) — não função nem
- *      variável. É a categoria que o grafo casa com confiança.
- *   2. Só MESMA LINGUAGEM. Contrato espelhado entre C# e TS (110 casos no
- *      ProspectPRO) é o escopo F da proposta: exige gerar tipos do contrato,
- *      não se resolve por aviso, e fica FORA daqui de propósito.
- *   3. Mesma feature = achado (`error`); feature diferente = aviso
- *      (`warning`), porque VSA prescreve DTO homônimo entre slices.
- *   4. Veredito `CRIAR` declarado na tabela de reuso do plano rebaixa o
- *      achado a aviso: a decisão foi tomada no gate do plano, com justificativa
- *      em `why`. O validador cobra a decisão AUSENTE, não a decisão tomada.
- *
- * Sem grafo o validador não roda (ADR-002: ausência de grafo nunca bloqueia).
- *
- * @module reuse-validator
- */
+// Só tipos, só mesma linguagem (contrato espelhado C#↔TS não se resolve por aviso).
+// Mesma feature = error; outra feature = warning (VSA admite DTO homônimo entre slices).
+// Veredito CRIAR no plano rebaixa a warning: cobra-se a decisão AUSENTE, não a tomada.
 
 import { existsSync, readFileSync } from 'fs';
 import { execFileSync } from 'child_process';
@@ -42,26 +16,15 @@ import {
 } from './symbol-scanner.js';
 import { readPlanChecks } from '../../plan/checks.js';
 
-/** Quantos locais citar por achado antes de resumir com "(+N)". */
 const MAX_CITED = 4;
 
-/**
- * Índice "o que já existe": nome em minúsculas -> ocorrências reais do grafo.
- *
- * Só nós com `source_file` preenchido entram — nó com `source_file: ""` é stub
- * não resolvido (BCL, NuGet, pacote externo), e apontar `Task` do .NET como
- * duplicação seria ruído garantido. É o mesmo critério do `buildIndex`.
- *
- * @param {{nodes: object[]}} graph
- * @returns {Map<string, Array<{name: string, file: string, language: string, feature: string}>>}
- */
 export function buildExistingIndex(graph) {
   const index = new Map();
 
   for (const node of graph?.nodes ?? []) {
+    // `source_file` vazio é stub não resolvido (BCL, NuGet): `Task` do .NET não é duplicação.
     if (!node.source_file) continue;
-    // `_callable_class` é a marca de tipo do graphify; nós de ARQUIVO também a
-    // carregam, e se distinguem pelo label com extensão.
+    // Nós de ARQUIVO também têm `_callable_class`; distinguem-se pelo label com extensão.
     if (node._callable_class !== true) continue;
     if (/\.[a-z0-9]+$/i.test(node.label)) continue;
     if (!isScannableFile(node.source_file)) continue;
@@ -81,23 +44,10 @@ export function buildExistingIndex(graph) {
   return index;
 }
 
-/**
- * Casa as declarações desta feature contra o que já existe.
- *
- * Puro e sem I/O — é aqui que a regra mora, e é isto que o teste roda contra o
- * grafo real do ProspectPRO.
- *
- * @param {Array<{name: string, kind: string, line: number, file: string}>} declarations
- * @param {Map<string, Array<{name: string, file: string, language: string, feature: string}>>} existing
- * @param {{verdicts?: Map<string, {verdict: string, target?: string}>}} [opts]
- * @returns {Array<object>} issues, uma por símbolo duplicado
- */
 export function findDuplicateSymbols(declarations, existing, opts = {}) {
   const verdicts = opts.verdicts ?? new Map();
   const issues = [];
 
-  // Uma declaração por (nome, arquivo); o mesmo nome em N arquivos da feature
-  // vira UM achado com N locais, não N achados.
   const byName = new Map();
   for (const decl of declarations) {
     const key = decl.name.toLowerCase();
@@ -112,17 +62,10 @@ export function findDuplicateSymbols(declarations, existing, opts = {}) {
     const declaredFiles = new Set(decls.map((d) => d.file));
     const language = languageOf(decls[0].file);
 
-    // Onde mais esse nome vive: no grafo (código que já existia) e nos OUTROS
-    // arquivos desta mesma leva (código novo que o grafo ainda não viu — ele
-    // só é refeito depois do commit, e é exatamente o caso SimpleBuilding).
+    // A leva também conta: o grafo só é refeito depois do commit e ainda não viu o código novo.
     const fromGraph = (existing.get(key) ?? []).filter(
       (e) => e.language === language && !declaredFiles.has(e.file),
     );
-    // O filtro de linguagem vale AQUI TAMBÉM, não só contra o grafo: uma leva
-    // que toca `CatalogContracts.cs` e `catalog.types.ts` declara `CatalogItem`
-    // nos dois, na mesma feature `Catalog/` — e sem este filtro isso vira erro,
-    // que é precisamente o contrato espelhado C#↔TS que a proposta separa no
-    // escopo F por não se resolver com aviso. Medido no MORPH_GHLBrain.
     const fromBatch = decls
       .slice(1)
       .filter((d) => languageOf(d.file) === language)
@@ -166,13 +109,6 @@ export function findDuplicateSymbols(declarations, existing, opts = {}) {
   });
 }
 
-/**
- * Vereditos de reuso do plano: a tabela `## Reuso` que o plan-check extraiu.
- *
- * @param {string} projectPath
- * @param {string} featureName
- * @returns {Map<string, {verdict: string, target?: string}>}
- */
 export function readReuseVerdicts(projectPath, featureName) {
   const verdicts = new Map();
   if (!featureName) return verdicts;
@@ -187,17 +123,8 @@ export function readReuseVerdicts(projectPath, featureName) {
   return verdicts;
 }
 
-/**
- * Arquivos que esta feature criou ou alterou.
- *
- * Duas fontes, unidas, porque cada uma é cega no momento em que a outra
- * enxerga: os `arquivos:` das fatias são o contrato do plano e sobrevivem ao
- * commit; `git status` pega o que o plano não previu. Sem git, sem drama.
- *
- * @param {string} projectPath
- * @param {string} featureName
- * @returns {string[]} paths relativos ao projeto, com barra normal
- */
+// União de duas fontes cegas em momentos diferentes: `arquivos:` das fatias sobrevivem
+// ao commit; `git status` pega o que o plano não previu.
 export function collectChangedFiles(projectPath, featureName) {
   const files = new Set();
   for (const slice of readPlanChecks(projectPath, featureName).checks?.slices ?? []) {
@@ -215,11 +142,7 @@ export function collectChangedFiles(projectPath, featureName) {
     });
     for (const line of out.split(/\r?\n/)) {
       if (!line.trim()) continue;
-      // "XY path" e, em rename, "XY antigo -> novo": só o destino interessa.
-      // Os paths vêm relativos à RAIZ do repositório — que no morph-spec é a
-      // própria árvore da feature (cada worktree é a sua raiz). Se algum dia
-      // não coincidir com `projectPath`, o `existsSync` adiante descarta o
-      // path: perde-se cobertura, nunca se acusa um arquivo que não existe.
+      // Rename vem como "XY antigo -> novo": só o destino interessa.
       const path = line.slice(3).split(' -> ').pop().replace(/^"|"$/g, '');
       if (path) files.add(path.replace(/\\/g, '/'));
     }
@@ -230,17 +153,6 @@ export function collectChangedFiles(projectPath, featureName) {
   return [...files];
 }
 
-/**
- * Validador plugado no `validation-runner` (e por ele no nó `validators` do
- * `morph-spec verify`).
- *
- * @param {string} projectPath
- * @param {string} featureName
- * @param {object} [options]
- * @param {string[]} [options.changedFiles] - override da coleta (testes)
- * @param {object} [options._graph] - grafo já carregado (testes)
- * @returns {Promise<{errors: number, warnings: number, issues: object[]}>}
- */
 export async function validateReuse(projectPath, featureName = null, options = {}) {
   const result = { errors: 0, warnings: 0, issues: [] };
 
@@ -250,11 +162,9 @@ export async function validateReuse(projectPath, featureName = null, options = {
   })();
 
   if (!graph) {
-    // ADR-002: projeto sem grafo (sem Python, ou grafo ainda não construído)
-    // segue em frente. Um validador que reprovasse aqui transformaria uma
-    // dependência opcional em pré-requisito.
+    // Sem grafo segue em frente: reprovar faria de uma dependência opcional um pré-requisito.
     result._skipReason = 'sem grafo de codebase — `morph-spec graph build` habilita esta verificação';
-    // "Could not check", unlike "nothing to check": verify reports it aloud.
+    // "Não pude checar", diferente de "nada a checar": o verify relata em voz alta.
     result._skipUnavailable = true;
     return result;
   }

package/src/lib/validators/reuse/symbol-scanner.js

@@ -1,74 +1,32 @@
-/**
- * Extração determinística de declarações de tipo a partir do TEXTO do arquivo.
- *
- * Por que não ler as declarações do grafo: o grafo só é reconstruído depois de
- * um commit (o refresh em background de framework/hooks/shared/graph-refresh.js),
- * então o código que acabou de ser escrito — o caso que este validador existe
- * para pegar — ainda NÃO está nele. O grafo responde "o que já existia"; o
- * disco responde "o que esta feature acabou de declarar". Inverter os dois
- * papéis produziria um validador cego justamente na janela em que ele precisa
- * morder — ver graph-loader.js `getFreshness`.
- *
- * A varredura é por linha, com regex ancorada no início da declaração: uma
- * declaração citada dentro de uma string ou de um comentário de bloco pode
- * passar. O custo de errar é um aviso a mais, nunca um bloqueio silencioso.
- *
- * @module reuse-symbol-scanner
- */
+// Lê declarações do disco, não do grafo: o grafo só é refeito depois de um commit,
+// então o código recém-escrito (o que este validador existe para pegar) ainda não está nele.
 
 import { isTestPath, languageOf } from '../../graph/sanitize.js';
 import { isProjectSource } from '../../../../framework/hooks/shared/source-files.js';
 
-/**
- * Nomes que a convenção usa como tipo LOCAL de arquivo, não como conceito do
- * domínio. Todo componente React declara o seu `Props`; dois arquivos com
- * `interface Props` não são o mesmo conceito escrito duas vezes — são dois
- * conceitos diferentes com o nome que a convenção manda usar.
- *
- * A lista é curta de propósito e só admite nome genérico de UMA palavra: assim
- * que há qualificador de domínio (`BuildingFiltersProps`, `FilterOption`) o
- * nome volta a ser um conceito e a regra vale.
- */
+// Tipo LOCAL de arquivo por convenção (todo componente tem seu `Props`), não conceito do
+// domínio. Só nome genérico de UMA palavra: com qualificador (`FilterOption`) a regra vale.
 const IDIOMATIC_LOCAL_NAMES = new Set([
   'props', 'state', 'row', 'item', 'column', 'context', 'params', 'options',
 ]);
 
-/** Declaração de tipo em C#. `partial` é capturado para ser excluído depois. */
 const CSHARP_DECL =
   /^\s*(?:\[[^\]]*\]\s*)*(?:(?:public|internal|private|protected|sealed|abstract|static|readonly|new|file|partial)\s+)*(class|record|interface|enum|struct)\s+([A-Za-z_]\w*)/;
 
-/** Declaração de tipo em TS/JS. */
 const WEB_DECL =
   /^\s*(?:export\s+(?:default\s+)?)?(?:declare\s+)?(?:abstract\s+)?(interface|type|class|enum)\s+([A-Za-z_$][\w$]*)/;
 
-/** Linha que é claramente comentário — não vale a pena parsear. */
 const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*|<!--)/;
 
-/**
- * @param {string} sourceFile
- * @returns {boolean} arquivo de teste, pelo mesmo predicado do grafo
- */
 export function isTestFile(sourceFile) {
   return isTestPath(String(sourceFile || '').replace(/\\/g, '/'));
 }
 
-/**
- * @param {string} sourceFile
- * @returns {boolean} o arquivo entra na varredura de reuso
- */
 export function isScannableFile(sourceFile) {
   return isProjectSource(sourceFile) && !isTestFile(sourceFile);
 }
 
-/**
- * "Feature" de um path, com a mesma heurística do baseline
- * (docs/specs/code-reuse-gap/measure-duplication.mjs): o segmento após
- * `features/`/`Features/` quando existe, senão a pasta do arquivo. É o que
- * separa o achado indefensável (mesma feature) do aviso tolerado por VSA.
- *
- * @param {string} sourceFile
- * @returns {string}
- */
+/** Segmento após `features/`/`Features/`, senão a pasta do arquivo. */
 export function featureOf(sourceFile) {
   const f = String(sourceFile || '').replace(/\\/g, '/');
   const m = /(?:^|\/)(?:features|Features)\/([^/]+)/.exec(f);
@@ -76,25 +34,11 @@ export function featureOf(sourceFile) {
   return f.split('/').slice(0, -1).join('/').toLowerCase();
 }
 
-/**
- * @param {string} name
- * @returns {boolean} nome genérico que a convenção usa como tipo local
- */
 export function isIdiomaticLocalName(name) {
   return IDIOMATIC_LOCAL_NAMES.has(String(name).toLowerCase());
 }
 
-/**
- * Declarações de tipo de um arquivo.
- *
- * `partial` (C#) é reconhecido e DESCARTADO: declarar a mesma classe em dois
- * arquivos é o propósito da palavra-chave, e sinalizá-la seria um falso
- * positivo garantido em qualquer projeto .NET com código gerado.
- *
- * @param {string} content - conteúdo do arquivo
- * @param {string} sourceFile - path, usado só para decidir a linguagem
- * @returns {Array<{name: string, kind: string, line: number}>}
- */
+// `partial` (C#) é descartado: declarar a mesma classe em dois arquivos é o propósito da palavra-chave.
 export function scanDeclarations(content, sourceFile) {
   const language = languageOf(sourceFile);
   const re = language === 'dotnet' ? CSHARP_DECL : WEB_DECL;