TypeScript ESLint 契约：守住异步、类型、模块三条边界

// 一个 as，把类型系统在此之后的全部检查都买断了
const callback = (await resp.json()) as PaymentCallback;
// 半年后在这里炸：Cannot read properties of undefined
const fee = callback.settlement.fee.amount;

// 反例一：忘了 await，失败被吞，上层以为成功了
saveAuditLog(orderId);

// 反例二：void 只声明"我故意不等"，rejection 依然没人接
void saveAuditLog(orderId);

// 正解：明确等待，或明确把失败纳入处理路径
await saveAuditLog(orderId).catch(err => reportDegraded(orderId, err));

// eslint.config.mjs（flat config，typescript-eslint v8）
import tseslint from 'typescript-eslint';

export default tseslint.config({
  files: ['src/**/*.{ts,tsx}'],
  extends: [tseslint.configs.recommendedTypeChecked],
  languageOptions: {
    parserOptions: {
      // true = 用离目标文件最近的 tsconfig；下面两条规则离开类型信息不会生效
      project: true,
      tsconfigRootDir: import.meta.dirname,
    },
  },
  rules: {
    '@typescript-eslint/no-floating-promises': 'error',
    // await 非异步值多半是把同步逻辑伪装成异步，掩盖真实的控制流错误
    '@typescript-eslint/await-thenable': 'error',
  },
});

// 解析层出口：守卫函数，过了这道门类型就是可信的
function isPaymentCallback(v: unknown): v is PaymentCallback {
  if (typeof v !== 'object' || v === null || !('settlement' in v)) return false;
  return typeof (v as { settlement: unknown }).settlement === 'object';
}

const raw: unknown = await resp.json();
if (!isPaymentCallback(raw)) throw new InvalidWebhookError('bad shape');
// settlement 的存在性从此由运行时保证，不再靠信仰

// 解析层收 any 但不许扩散；业务层连 any 都不许有
{
  files: ['src/api/**/*.ts'],
  rules: {
    '@typescript-eslint/no-explicit-any': 'off',
    // 从 any 出发的取值/调用/传参/返回全部报错，逼你在出口处收窄
    '@typescript-eslint/no-unsafe-assignment': 'error',
    '@typescript-eslint/no-unsafe-member-access': 'error',
    '@typescript-eslint/no-unsafe-call': 'error',
    '@typescript-eslint/no-unsafe-return': 'error',
    '@typescript-eslint/no-unsafe-argument': 'error',
  },
},
{
  files: ['src/features/**/*.{ts,tsx}'],
  rules: { '@typescript-eslint/no-explicit-any': 'error' },
},

'@typescript-eslint/ban-ts-comment': ['error', {
  'ts-expect-error': 'allow-with-description',  // 允许，但必须写原因
  'ts-ignore': true,                            // 无条件禁止
  'ts-nocheck': true,
  minimumDescriptionLength: 10,                 // 逼原因写得像句话
}],

{
  files: ['src/**/*.{ts,tsx}'],
  rules: {
    'no-restricted-imports': ['error', {
      patterns: [{ group: ['**/features/*/internal/**'],
                   message: 'feature 内部不对外：请从该 feature 的 index.ts 导入' }],
    }],
  },
},

import boundaries from 'eslint-plugin-boundaries';

{
  files: ['src/**/*.{ts,tsx}'],
  plugins: { boundaries },
  settings: {
    'boundaries/include': ['src/features/**', 'src/shared/**'],
    'boundaries/elements': [
      { type: 'feature', pattern: 'src/features/*', capture: ['feature'] },
      { type: 'feature-internal', pattern: 'src/features/*/internal/**', capture: ['feature'] },
      { type: 'shared', pattern: 'src/shared/*' },
    ],
  },
  rules: {
    // 谁能引用谁：feature 只能碰 shared 和自己；shared 只能碰 shared
    'boundaries/element-types': ['error', {
      default: 'disallow',
      rules: [
        { from: ['feature'], allow: [['feature-internal', { feature: '${from.feature}' }], 'shared'] },
        { from: ['feature-internal'], allow: [['feature-internal', { feature: '${from.feature}' }], 'shared'] },
        { from: ['shared'], allow: ['shared'] },
      ],
    }],
    // 内部文件禁止被元素外部的文件引用："只认 index"靠它落地
    'boundaries/external': ['error', {
      default: 'allow',
      rules: [{ from: ['feature'], disallow: ['feature-internal'] }],
    }],
  },
},

import noOnlyTests from 'eslint-plugin-no-only-tests';
{
  files: ['tests/**/*.ts'],
  plugins: { 'no-only-tests': noOnlyTests },
  rules: { 'no-only-tests/no-only-tests': 'error' },
},

// 允许的样子
// eslint-disable-next-line @typescript-eslint/no-floating-promises -- 审计日志失败可降级，处理路径见 OPS-1042
notify(orderId);

// 失效的 disable 直接报错（flat config）
linterOptions: { reportUnusedDisableDirectives: 'error' },

#!/usr/bin/env bash
# CI：disable 数量超过基线即失败，基线只能随清理 MR 下降
set -euo pipefail

CURRENT=$(grep -rE 'eslint-disable(-next-line|-line)? ' src tests \
  --include='*.ts' --include='*.tsx' | wc -l | tr -d ' ')
BASELINE=$(cat scripts/lint-disable-baseline.txt)

if [ "$CURRENT" -gt "$BASELINE" ]; then
  echo "eslint-disable: $BASELINE -> $CURRENT，禁止新增；请清理存量后更新基线" >&2
  exit 1
fi

{
  // 测试代码：fixture 与 mock 上 no-unsafe-* 噪音远大于收益
  files: ['tests/**/*.ts'],
  rules: {
    '@typescript-eslint/no-unsafe-assignment': 'off',
    '@typescript-eslint/no-explicit-any': 'off',
  },
},
{
  // 生成代码：disableTypeChecked 展开为关闭全部类型感知规则，官方姿势
  files: ['src/generated/**/*.ts'],
  ...tseslint.configs.disableTypeChecked,
},

# 确认规则真的落在某个角落文件上
npx eslint --print-config src/features/checkout/internal/pricing.ts \
  | jq '."rules"["@typescript-eslint/no-floating-promises"]'
# 期望输出 ["error"]；输出 null 就是静默失效

# 兜底：故意在一个角落文件写一个 floating promise，确认 CI 会红