wrapper-enforcement

Impõe o uso de um wrapper do projeto em vez de uma API de plataforma crua.

Detalhes da regra

Quando um projeto fornece um helper que normaliza uma API de baixo nível (ex.: um helper platform.ts encapsulando process.platform), o uso direto da API crua deve ser banido em todos os lugares exceto no próprio wrapper. Esta regra varre os arquivos no escopo procurando a chamada da API crua enquanto exclui automaticamente o arquivo helper e o código que não é de produção.

Exemplos de código incorreto

src/commands/build.ts

if (process.platform === "win32") {
  // Windows-specific logic
}

Exemplos de código correto

src/commands/build.ts

import { isWindows } from "../helpers/platform";

if (isWindows()) {
  // Windows-specific logic
}

Implementação da regra

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-direct-process-platform": {
      description:
        "Platform detection must use src/helpers/platform.ts, not process.platform directly",
      async check(ctx) {
        const files = ctx.scopedFiles.filter(
          (f) =>
            !f.includes("tests/") &&
            !f.includes(".archgate/") &&
            !f.endsWith("src/helpers/platform.ts") // Exclude the wrapper itself
        );

        const matches = await Promise.all(
          files.map((file) => ctx.grep(file, /process\.platform/))
        );
        for (const fileMatches of matches) {
          for (const m of fileMatches) {
            ctx.report.violation({
              message:
                "Não acesse process.platform diretamente. Use isWindows(), isMacOS(), isLinux() ou getPlatformInfo() de src/helpers/platform.ts.",
              file: m.file,
              line: m.line,
              fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform',
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;

Quando usar

Quando seu projeto possui um módulo wrapper ou helper que normaliza uma API crua e você deseja impedir o acesso direto à API subjacente. Exemplos comuns:

• platform.ts encapsulando process.platform
• logger.ts encapsulando console.log / console.error
• fs.ts encapsulando node:fs com padrões específicos do projeto
• env.ts encapsulando process.env com acessores tipados

Quando não usar

Quando a API crua é simples o suficiente para que um wrapper não agregue valor, ou quando o wrapper ainda não foi adotado em toda a base de código (considere usar severidade warning durante a migração).