@skapxd/eslint-opinionated 0.16.0 → 0.17.0

package/README.md

@@ -748,6 +748,19 @@ export default [
 ];
 ```
 
+Para librerías npm escritas en TypeScript (tsup o equivalente). Trae las
+bases completas + el set type-driven (tipado, con `projectService`) +
+`await-requires-result` + el contrato de empaquetado:
+
+- `skapxd/package-requires-typed-exports` — los `exports` del package.json
+  cablean los tipos **por condición** (`import` → `.d.mts`, `require` →
+  `.d.ts`); el `types` único por subpath es el bug "FalseCJS".
+- `skapxd/untrusted-module-requires-adapter` — inerte hasta que declares tu
+  inventario de paquetes con tipos mentirosos (ver su sección).
+
+**Este mismo repo se lintea con este preset** — dogfood: la regla de exports
+nos obligó a corregir nuestro propio package.json al nacer.
+
 ### Strict (sin escape via `eslint-disable`)
 
 Un prompt o un agente puede saltarse cualquier regla con
@@ -831,7 +844,9 @@ de cada regla):
 | `no-runtime-state-guard` | `allowFilePatterns` (globs) |
 | `no-tunnel-props` | `allowFilePatterns` (globs), `allowPropPatterns` (regex) |
 | `prefer-abort-signal` | `allowFilePatterns` (globs), `effectNames` (default `["useEffect", "useLayoutEffect"]`) |
+| `package-requires-typed-exports` | `allowFilePatterns` (globs), `anchorFilePatterns` (default `src/index.ts(x)`, `src/main.ts`) |
 | `prefer-tagged-union-state` | `allowFilePatterns` (globs), `loadingPatterns` (regex, en minúsculas), `errorPatterns` (regex, en minúsculas) |
+| `untrusted-module-requires-adapter` | `modules` (default `[]` — inerte), `adapterFilePatterns` (globs), `allowFilePatterns` (globs) |
 | `requires-strict-tsconfig` | `allowFilePatterns` (globs), `anchorFilePatterns` (globs), `requiredCompilerOptions` |
 | `result-error-requires-handling` | `allowFilePatterns` (globs) |
 
@@ -883,6 +898,8 @@ matchea en cualquier carpeta). Las 7 reglas restantes no tienen opciones: su
 | `skapxd/no-try-catch` | Prohíbe `try/catch`; usa `trySafe` de `@skapxd/result`. |
 | `skapxd/no-promise-chain` | Prohíbe `.then/.catch/.finally`; usa `await` (+ `trySafe`). |
 | `skapxd/prefer-ts-pattern` | Prohíbe `switch` y ternarios anidados; usa `match()` de ts-pattern. |
+| `skapxd/package-requires-typed-exports` | Los `exports` del package.json declaran `types` por condición (`import` → `.d.mts`, `require` → `.d.ts`): mata el bug FalseCJS. Preset `package`. |
+| `skapxd/untrusted-module-requires-adapter` | Los paquetes con tipos mentirosos (@types desfasados) solo se importan desde su adaptador: la mentira vive en UN archivo. Preset `package`. |
 | `skapxd/no-jsx-ternary-null` | Prefiere `cond && <El />` sobre `cond ? <El /> : null` en JSX. |
 
 ### `skapxd/one-root-function-per-file`
@@ -2229,6 +2246,68 @@ no puede traer `signal`.
 `effectNames` permite cubrir wrappers propios (`["useEffect",
 "useLayoutEffect", "useIsomorphicEffect"]`).
 
+### `skapxd/package-requires-typed-exports`
+
+El contrato de empaquetado de una librería TypeScript dual (ESM + CJS): cada
+condición del mapa `exports` declara **sus propios tipos**, del sabor
+correcto.
+
+```jsonc
+"exports": {
+  ".": {
+    "import": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" },
+    "require": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }
+  }
+}
+```
+
+El antipatrón que mata es el **"FalseCJS"** (el hallazgo #1 de
+[arethetypeswrong](https://arethetypeswrong.github.io)): un `types` único por
+subpath apuntando al `.d.ts` — los consumidores ESM con
+`moduleResolution: node16` reciben tipos CJS y el contrato miente en la
+frontera más pública que tiene una librería. tsup con `dts: true` ya genera
+los dos sabores (`.d.mts` y `.d.ts`); esta regla verifica que el package.json
+de verdad los cablee y que los archivos existan en disco. Anclada al
+entrypoint (`src/index.ts` por defecto): un reporte por paquete.
+
+Dogfood: esta regla nació reportando a este mismo repo — nuestros `exports`
+tenían el bug y el lint no volvió a verde hasta corregirlos.
+
+### `skapxd/untrusted-module-requires-adapter`
+
+¿Qué pasa cuando los tipos de un paquete de terceros **mienten**? El clásico:
+un paquete escrito en JS cuyos tipos viven aparte (`@types/...`) y van
+desfasados del runtime real, o índices que juran nunca devolver `undefined`.
+Todo el sistema de este paquete descansa en que el tipo dice la verdad
+(`no-impossible-branch` le cree ciegamente) — un tipo mentiroso envenena cada
+regla type-aware que lo toque.
+
+El playbook, en orden:
+
+1. **Armadura de tsconfig primero**: `noUncheckedIndexedAccess` corrige de
+   raíz la clase más común de mentira (index signatures optimistas) sin
+   tocar al tercero — `requires-strict-tsconfig` ya lo exige.
+2. **Frontera anticorrupción** (lo que esta regla impone): declara el módulo
+   como no confiable y enciérralo tras UN adaptador. El adaptador importa el
+   paquete, re-declara los tipos honestos (lo que el runtime de verdad
+   devuelve) y exporta esa versión. El resto del código importa el adaptador
+   y razona con tipos veraces — la mentira queda en un archivo auditable.
+3. **`@ts-expect-error` con descripción** dentro del adaptador si hace falta
+   forzar la corrección — es la puerta que `no-silenced-compiler` deja
+   abierta, declarada y con porqué.
+4. **Arregla el upstream**: PR a DefinitelyTyped. Mientras llega, los pasos
+   1-3 te protegen.
+
+```js
+"skapxd/untrusted-module-requires-adapter": ["error", {
+  adapterFilePatterns: ["src/lib/xlsx-adapter.ts"],
+  modules: ["xlsx"],
+}]
+```
+
+Sin `modules` declarados la regla es inerte: el inventario de sospechosos es
+una decisión del proyecto, no una adivinanza del linter (axioma A5).
+
 ### `skapxd/no-jsx-ternary-null`
 
 Cuando renderizas JSX condicional y una rama del ternario es `null`, prefiere la

package/dist/astro/index.mjs

@@ -1,7 +1,7 @@
 import {
   createAstroConfigs
-} from "../chunk-7OIMY5TI.mjs";
-import "../chunk-4FQ7SFU4.mjs";
+} from "../chunk-GSQWHSHV.mjs";
+import "../chunk-QDQUU6QK.mjs";
 export {
   createAstroConfigs
 };

package/dist/{chunk-LSLLVT64.mjs → chunk-3GEFHNU7.mjs}

@@ -2,7 +2,7 @@ import {
   baseRules,
   createTypedLanguageOptions,
   typeDrivenRules
-} from "./chunk-4FQ7SFU4.mjs";
+} from "./chunk-QDQUU6QK.mjs";
 
 // src/constants/nest-entrypoint-file-patterns.ts
 var nestEntrypointFilePatterns = [
@@ -130,4 +130,4 @@ function createNestConfigs(pluginReference) {
 export {
   createNestConfigs
 };
-//# sourceMappingURL=chunk-LSLLVT64.mjs.map
+//# sourceMappingURL=chunk-3GEFHNU7.mjs.map

package/dist/{chunk-YRWX3POD.mjs → chunk-54EOEKYS.mjs}

@@ -6,7 +6,7 @@ import {
   baseRules,
   createBaseLanguageOptions,
   createTypedLanguageOptions
-} from "./chunk-4FQ7SFU4.mjs";
+} from "./chunk-QDQUU6QK.mjs";
 
 // src/next/configs.ts
 var nextDefaultExportFileGlob = `{${[
@@ -71,4 +71,4 @@ function createNextConfigs(pluginReference) {
 export {
   createNextConfigs
 };
-//# sourceMappingURL=chunk-YRWX3POD.mjs.map
+//# sourceMappingURL=chunk-54EOEKYS.mjs.map

package/dist/{chunk-7OIMY5TI.mjs → chunk-GSQWHSHV.mjs}

@@ -2,7 +2,7 @@ import {
   baseRules,
   createBaseLanguageOptions,
   createTypedLanguageOptions
-} from "./chunk-4FQ7SFU4.mjs";
+} from "./chunk-QDQUU6QK.mjs";
 
 // src/astro/configs.ts
 function createAstroConfigs(pluginReference) {
@@ -41,4 +41,4 @@ function createAstroConfigs(pluginReference) {
 export {
   createAstroConfigs
 };
-//# sourceMappingURL=chunk-7OIMY5TI.mjs.map
+//# sourceMappingURL=chunk-GSQWHSHV.mjs.map

package/dist/{chunk-X2DU5BAB.mjs → chunk-PD77UDUY.mjs}

@@ -2761,8 +2761,14 @@ var noEmoji = {
 
 // src/utils/wrap-tseslint-rule.ts
 import tseslint from "typescript-eslint";
+var upstreamRules = tseslint.plugin.rules;
 function wrapTseslintRule(upstreamRuleName, { description, messages }) {
-  const original = tseslint.plugin.rules[upstreamRuleName];
+  const original = upstreamRules[upstreamRuleName];
+  if (!original) {
+    throw new Error(
+      `wrapTseslintRule: la regla "${upstreamRuleName}" no existe en typescript-eslint.`
+    );
+  }
   return {
     ...original,
     meta: {
@@ -2856,7 +2862,10 @@ function getNoTunnelPropsOptions(options = {}) {
 
 // src/utils/get-object-pattern-prop-names.ts
 function getObjectPatternPropNames(pattern) {
-  const result = { propNames: [], restName: null };
+  const result = {
+    propNames: [],
+    restName: null
+  };
   if (pattern?.type !== "ObjectPattern") {
     return result;
   }
@@ -3494,7 +3503,7 @@ function readResolvedTsconfig(tsconfigPath) {
   if (!parsed.ok || !parsed.value) {
     return null;
   }
-  return parsed.value.options ?? null;
+  return parsed.value.options;
 }
 
 // src/rules/requires-strict-tsconfig.ts
@@ -3841,6 +3850,212 @@ var noRuntimeStateGuard = {
   }
 };
 
+// src/rules/package-requires-typed-exports.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname6, resolve as resolve3 } from "path";
+import { trySafe as trySafe4 } from "@skapxd/result";
+
+// src/utils/get-typed-exports-options.ts
+function getTypedExportsOptions(options = {}) {
+  return {
+    allowFilePatterns: options.allowFilePatterns ?? [],
+    // Anclada al entrypoint de la libreria: un reporte por paquete.
+    anchorFilePatterns: options.anchorFilePatterns ?? [
+      "src/index.ts",
+      "src/index.tsx",
+      "src/main.ts"
+    ]
+  };
+}
+
+// src/utils/get-untyped-export-conditions.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+function getUntypedExportConditions(exportsField, packageDir) {
+  const violations = [];
+  const entries = "import" in exportsField || "require" in exportsField ? [[".", exportsField]] : Object.entries(exportsField);
+  for (const [subpath, value] of entries) {
+    if (subpath === "./package.json") {
+      continue;
+    }
+    if (typeof value === "string") {
+      violations.push({ kind: "untyped", condition: "todas", subpath });
+      continue;
+    }
+    for (const condition of ["import", "require"]) {
+      if (!(condition in value)) {
+        continue;
+      }
+      const target = value[condition];
+      if (typeof target !== "object" || typeof target.types !== "string") {
+        violations.push({ kind: "untyped", condition, subpath });
+        continue;
+      }
+      const expectsEsmTypes = condition === "import";
+      const flavorOk = expectsEsmTypes ? target.types.endsWith(".d.mts") : target.types.endsWith(".d.ts") || target.types.endsWith(".d.cts");
+      if (!flavorOk) {
+        violations.push({ kind: "wrong-flavor", condition, subpath });
+        continue;
+      }
+      if (!existsSync3(join3(packageDir, target.types))) {
+        violations.push({ kind: "missing-file", condition, subpath });
+      }
+    }
+  }
+  return violations;
+}
+
+// src/rules/package-requires-typed-exports.ts
+var kindMessages = {
+  "missing-file": "missingTypesFile",
+  untyped: "untypedCondition",
+  "wrong-flavor": "wrongTypesFlavor"
+};
+var packageRequiresTypedExports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "El package.json de una libreria debe cablear los tipos POR CONDICION en exports: import \u2192 .d.mts, require \u2192 .d.ts. Un types unico es el bug FalseCJS."
+    },
+    messages: {
+      missingExports: "El package.json no tiene campo `exports`. Sin el, Node y TypeScript resuelven por heuristicas viejas y los consumidores ESM/CJS pueden recibir artefactos cruzados. Declara el mapa de exports con `types` por condicion.",
+      missingTypesFile: 'En exports["{{subpath}}"].{{condition}}, el archivo de `types` declarado no existe en disco. El contrato apunta a un fantasma: o falta el build (dts) o la ruta esta mal escrita.',
+      unreadablePackageJson: "No encontre un package.json legible subiendo desde este archivo. Esta regla valida el contrato de tipos de la libreria y necesita leerlo.",
+      untypedCondition: 'exports["{{subpath}}"] \u2192 `{{condition}}` no declara su propio `types`. Un `types` unico a nivel del subpath es el bug "FalseCJS": el consumidor ESM con moduleResolution node16 recibe los tipos CJS. Cada condicion declara los suyos \u2014 `import` como objeto con `types: ./dist/x.d.mts` y `default: ./dist/x.mjs`; `require` como objeto con `types: ./dist/x.d.ts` y `default: ./dist/x.js`.',
+      wrongTypesFlavor: 'exports["{{subpath}}"].{{condition}} apunta a tipos del formato equivocado: `import` exige `.d.mts` (tipos ESM) y `require` exige `.d.ts`/`.d.cts` (tipos CJS). tsup con dts: true ya genera ambos sabores.'
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowFilePatterns: {
+            items: { type: "string" },
+            type: "array"
+          },
+          anchorFilePatterns: {
+            items: { type: "string" },
+            type: "array"
+          }
+        },
+        type: "object"
+      }
+    ]
+  },
+  create(context) {
+    const options = getTypedExportsOptions(context.options[0]);
+    const filename = context.filename ?? context.getFilename();
+    if (matchesAnyGlob(filename, options.allowFilePatterns) || !matchesAnyGlob(filename, options.anchorFilePatterns)) {
+      return {};
+    }
+    return {
+      Program(node) {
+        const absoluteFilename = resolve3(context.cwd ?? process.cwd(), filename);
+        const packageJsonPath = findProjectFile(
+          dirname6(absoluteFilename),
+          "package.json"
+        );
+        const parsed = packageJsonPath ? trySafe4(() => JSON.parse(readFileSync2(packageJsonPath, "utf8"))) : null;
+        if (!parsed || !parsed.ok) {
+          context.report({ messageId: "unreadablePackageJson", node });
+          return;
+        }
+        const exportsField = parsed.value.exports;
+        if (!exportsField || typeof exportsField !== "object") {
+          context.report({ messageId: "missingExports", node });
+          return;
+        }
+        const violations = getUntypedExportConditions(
+          exportsField,
+          dirname6(packageJsonPath)
+        );
+        for (const violation of violations) {
+          context.report({
+            data: {
+              condition: violation.condition,
+              subpath: violation.subpath
+            },
+            messageId: kindMessages[violation.kind],
+            node
+          });
+        }
+      }
+    };
+  }
+};
+
+// src/utils/get-untrusted-module-options.ts
+function getUntrustedModuleOptions(options = {}) {
+  return {
+    // Globs de los archivos adaptador: el UNICO lugar desde donde se permite
+    // importar los modulos declarados como no confiables.
+    adapterFilePatterns: options.adapterFilePatterns ?? [],
+    allowFilePatterns: options.allowFilePatterns ?? [],
+    // Inventario de paquetes cuyos tipos mienten (p. ej. @types desfasados).
+    // Vacio por defecto: la regla es inerte hasta que el proyecto declara
+    // sus sospechosos.
+    modules: options.modules ?? []
+  };
+}
+
+// src/rules/untrusted-module-requires-adapter.ts
+var untrustedModuleRequiresAdapter = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Los modulos declarados como no confiables (tipos que mienten) solo se importan desde su adaptador: la mentira vive en un archivo, no en todos."
+    },
+    messages: {
+      untrustedImport: "`{{moduleSource}}` esta declarado como modulo de tipos NO confiables: importalo solo desde su adaptador ({{adapters}}). El adaptador es la frontera anticorrupcion: re-declara ahi los tipos honestos (lo que el runtime de verdad devuelve) y exporta esa version; el resto del codigo importa el adaptador y razona con tipos veraces. Asi la mentira de terceros vive en UN archivo auditable, no regada por el proyecto."
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          adapterFilePatterns: {
+            items: { type: "string" },
+            type: "array"
+          },
+          allowFilePatterns: {
+            items: { type: "string" },
+            type: "array"
+          },
+          modules: {
+            items: { type: "string" },
+            type: "array"
+          }
+        },
+        type: "object"
+      }
+    ]
+  },
+  create(context) {
+    const options = getUntrustedModuleOptions(context.options[0]);
+    const filename = context.filename ?? context.getFilename();
+    if (options.modules.length === 0 || matchesAnyGlob(filename, options.allowFilePatterns) || matchesAnyGlob(filename, options.adapterFilePatterns)) {
+      return {};
+    }
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        const isUntrusted = options.modules.some(
+          (moduleName) => source === moduleName || source.startsWith(`${moduleName}/`)
+        );
+        if (!isUntrusted) {
+          return;
+        }
+        context.report({
+          data: {
+            adapters: options.adapterFilePatterns.join(", ") || "sin definir",
+            moduleSource: source
+          },
+          messageId: "untrustedImport",
+          node
+        });
+      }
+    };
+  }
+};
+
 // src/shared/rules.ts
 var rules = {
   "class-properties-require-readonly": classPropertiesRequireReadonly,
@@ -3893,10 +4108,12 @@ var rules = {
   "no-jsx-ternary-null": noJsxTernaryNull,
   "no-nested-if": noNestedIf,
   "no-promise-chain": noPromiseChain,
-  "no-runtime-state-guard": noRuntimeStateGuard
+  "no-runtime-state-guard": noRuntimeStateGuard,
+  "package-requires-typed-exports": packageRequiresTypedExports,
+  "untrusted-module-requires-adapter": untrustedModuleRequiresAdapter
 };
 
 export {
   rules
 };
-//# sourceMappingURL=chunk-X2DU5BAB.mjs.map
+//# sourceMappingURL=chunk-PD77UDUY.mjs.map