wrapper-enforcement

Håndhev bruk av en prosjektinnpakning i stedet for et rått plattform-API.

Regeldetaljer

Når et prosjekt tilbyr en hjelper som normaliserer et lavnivå-API (f.eks. en platform.ts-hjelper som innpakker process.platform), bør direkte bruk av det rå API-et forbys overalt unntatt i innpakningen selv. Denne regelen skanner omfangsfiler etter det rå API-kallet og ekskluderer automatisk hjelpefilen og ikke-produksjonskode.

Eksempler på feil kode

src/commands/build.ts

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

Eksempler på riktig kode

src/commands/build.ts

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

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

Regelimplementasjon

/// <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:
                "Do not access process.platform directly — use isWindows(), isMacOS(), or isLinux() from src/helpers/platform.ts instead.",
              file: m.file,
              line: m.line,
              fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform',
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;

Når du bør bruke den

Når prosjektet ditt har en innpakning eller hjelpemodul som normaliserer et rått API og du vil forhindre direkte tilgang til det underliggende API-et. Vanlige eksempler:

• platform.ts som innpakker process.platform
• logger.ts som innpakker console.log / console.error
• fs.ts som innpakker node:fs med prosjektspesifikke standardverdier
• env.ts som innpakker process.env med typede aksessorer

Når du ikke bør bruke den

Når det rå API-et er enkelt nok til at en innpakning ikke tilfører verdi, eller når innpakningen ennå ikke er tatt i bruk på tvers av kodebasen (vurder å bruke warning-alvorlighetsgrad under migrering).