@lintest/cli

Lintest CLI

Copyright 2024. mornya. All rights reserved.

About

Integrated lint and test environment project.

Features

• TypeScript and ES6+ support.
• Linting TypeScript / JavaScript codes with ESLint.
• Testing codes with Jest.
• Availabled for Node.js / React.js (Next.js) / Vue.js (Nuxt.js) applications.

Installation

해당 라이브러리는 글로벌 영역에 설치한다.

npm 대신 yarn 사용시, 프로젝트 루트 경로에 package-lock.json 파일이 존재하면 제거하고 yarn.lock 파일만 참조되도록 한다.

$ npm install -g @lintest/cli
or
$ yarn global add @lintest/cli

Execution

Commands

$ lintest <action> [option]

사용가능한 action은 아래와 같다.

• install: 린트 룰셋 패키지 설치 및 lintest 정보 생성, 모듈 업그레이드 등 수행
• uninstall: 생성된 정보 및 복사된 파일 등 install/export 수행에 따른 관련 파일 제거
• export: 린트 및 테스트 환경설정 내용을 JSON 파일로 출력하여 IDE에서 설정이 참조되도록 함
• check: TypeScript 컴파일러를 실행시켜 프로젝트 내 코드 오류 검사 수행
• clean: 기본적으로 dist 및 node_modules/.cache 디렉토리의 내용을 비우지만, 파라미터로 인입된 디렉토리(들)이 존재시 해당 디렉토리의 내용을 비움
• lint: 프로젝트 내 코드에 대한 린트 수행
• test: 프로젝트 내 테스트 코드에 대한 테스트케이스 수행
• list: 기본 ESLint 플러그인과 추가적으로 설치된 플러그인 목록을 표시
• help: 각 액션에 대한 도움말 표시

옵션에 대한 도움말은 아래와 같이 커맨드를 입력하여 확인한다.

# 액션 커맨드 도움말
$ lintest --help

# 액션에 대한 옵션 커맨드 도움말
$ lintest help [lint|test|...]

CLI

lintest 환경설정은 프로젝트 루트 경로에 lintest.config.js 혹은 lintest.config.json 등의 파일로 생성하면 된다.
lintest 실행시 프로젝트에 해당 설정 파일이 존재하면 lintest install 명령을 수행할 때 provider항목으로 지정된 룰셋 패키지가 NPM 글로벌 영역에 설치(업데이트) 되며, 린트 룰셋은 해당 패키지 내 설정에 따르게 된다.

// lintest.config.js

module.exports = {
  provider: 'sample', // required

  // If your project uses the Next.js or Nuxt.js framework,
  // specify it to avoid plugin confusion when doing ESLint.
  framework: 'next', // or 'nuxt'

  // optionals below
  exportConfig: {
    lint: 'eslint.config.json', // export ESLint config to filename (related project path)
    test: 'jest.config.json', // export Jest config to filename
    prettier: '.prettierrc', // export Prettier config to filename (if prettier configured)
  },

  // set location of the cache file or directory
  cacheLocation: {
    lint: '.eslintcache', // default: node_modules/.cache/lintest/eslintcache
    test: '.jestcache', // default: node_modules/.cache/lintest/jestcache
  },

  // You can customize with additional ESLint plugins by overriding options
  installPlugins: [
    'eslint-plugin-something@latest',
    'eslint-plugin-simple-import-sort',
  ],
  // Also can customize with additional Jest environments
  // and give an option "--env" to test that environment
  installEnvironments: [
    'jest-environment-selenium',
  ],

  // Override and customize
  overrides: {
    lintRules: { ... }, // overriding provider's lint rules
    eslint: [ // just same as ESLint "overrides" option
      {
        // the samples for using simple-import-sort plugin
        files: '*.vue',
        plugins: ['eslint-plugin-simple-import-sort'],
        rules: {
          'simple-import-sort/imports': 'error',
          'simple-import-sort/exports': 'error',
        },
      },
    ],
    jest: {
      bail: false,
      // ("testURL" option has been replaced as shown below) 
      testEnvironmentOptions: {
        url: 'https://localhost:8443'
      },
      ...
    },
  }
}

위와 같이 설정하면 lintest install 명령 실행시 @lintest/rules-sample 패키지가 글로벌 영역에 설치가 되며 프로젝트의 린트 룰셋은 해당 패키지에 선언된 설정을 따른다.
그리고 lintest export 명령 실행시 exportConfig에 선언된 파일들로 ESLint 룰셋과 Jest, Prettier 설정이 출력된다.

rules 디펜던시 생성은 아래에서 다룬다.

린트 및 테스트 수행은 CLI로 실행하며, 커맨드라인에서 아래와 같이 실행 할 수 있다.

# 린트 실행시
$ lintest lint [--fix][--debug][--no-cache][...]

# 테스트 실행시
$ lintest test [--coverage][--watch][--debug][--no-cache][...]

린트 및 테스트 환경설정 내용이 필요할 경우 export 명령을 사용하여 환경설정을 참고할 수 있다.
수행결과는 프로젝트 루트 경로에 ESLint 환경설정 파일 및 Jest 환경설정 파일이 출력된다 (lintest.config 파일에서 지정한 파일경로로 변경 가능).
만약 정상적인 출력이 되지 않는다면 debug 파라미터로 확인한다.

$ lintest export [--debug]

NPM

NPM 프로젝트에서는 npm run 명령으로 실행되도록 아래와 같이 package.json 파일 내에 설정한다.

{
  "scripts": {
    "check": "lintest check",
    "clean": "lintest clean",
    "lint": "lintest lint",
    "lint:fix": "lintest lint --fix",
    "lint:debug": "lintest lint --debug --no-cache",
    "test": "lintest test",
    "test:watch": "lintest test --watch",
    "test:coverage": "lintest test --coverage --no-cache"
  }
}

프로젝트에서 npm install 명령이 실행된 후에 lintest 업데이트 및 룰 업데이트를 자동으로 수행해 줄 수 있도록 아래와 같이 설정할 수도 있다.

• exit 0은 lintest가 설치되어 있지 않을 경우, 오류로 인해 다음 프로세스가 동작하지 않는 것을 방지하기 위해 정상종료로 처리하도록 해준다.
  
• 로컬 개발환경이 아닌 테스트/운영환경에서 lintest 미설치로 인해 오류가 발생하지 않도록 주의.

{
  "scripts": {
    "postinstall": "lintest install || exit 0",
    "postuninstall": "lintest install || exit 0",
    "prepare": "lintest export || exit 0"
  }
}

Testing

테스트케이스를 수행하기 위해 CLI의 디펜던시로 설치된 jest 바이너리가 실행된다.
테스트 파일은 프로젝트 내 존재하는 *.{test,spec}.{ts,tsx,js,jsx} 파일들이 테스트 대상이 된다.

Setup files

각 단위 테스트를 수행하기 전 mocking method나 초기 설정을 할 수 있도록 셋업 파일을 추가 할 수 있다. 적용될 테스트 셋업 파일은 아래 목록에서 존재하는 파일을 모두 찾아 사용하게 된다.

자세한 내용은 Jest 관련 문서를 참고.

<rootDir>/src/test/@setup.ts (or .js|cjs|cts|mjs|mts)
<rootDir>/src/tests/@setup.ts
<rootDir>/test/@setup.ts
<rootDir>/tests/@setup.ts
<rootDir>/test-setup.ts

Test Coverage

아래 명령으로 테스트 커버리지 데이터를 프로젝트 내 /coverage 디렉토리에 생성할 수 있다.

$ lintest test --coverage

Lint rules package

Naming

패키지명은 @lintest/rules-{프로바이더명}으로 정의하고 NPM @lintest 조직의 승인을 받아 배포함으로써 CLI에서 해당 패키지를 받아 린트 룰을 적용 할 수 있게 된다.

Package defination

package.json의 "main"으로 설정된 파일(index.js)에 아래와 같은 단일 형태의 정의 파일이 기본적으로 필요하다.
설정가능 항목은 prettier, lintRules, disableLintIgnore, enableCompatibility 등이 있다.

prettier

• prettier 항목은 prettier 사용이 필요할 때만 명시하면 된다.

lintRules

아래 샘플처럼 설정해주면 lintest에서 설정에 따라 여러 플러그인을 조합하여 최종 린트 룰셋을 만들어낸다.

• lintRules 하위 항목의 룰에 대한 선언은 플러그인별 prefix를 붙이지 않아도 되며, 불필요시 명시하지 않아도 된다.

  예를 들어, typescript 항목의 '@typescript-eslint/indent' 룰을 정의할 때 '@typescript-eslint/'는 굳이 붙여주지 않아도 'typescript' 항목 하위에 'indent'만으로 선언해도 최종 룰은 '@typescript-eslint/indent'로 변환된다.

• lintRules 하위 항목 중 vue 혹은 react 룰이 명시되면 관련 룰셋이 함께 적용된다.

  vue는 "eslint-plugin-vue", "@vue/standard", "@vue/typescript" 등 적용.
  react는 "eslint-plugin-jsx-a11y", "eslint-plugin-react", "eslint-plugin-react-hooks" 등 적용.

• 사용하지 않을 룰은 해당 항목을 주석처리 해두거나 삭제하면 된다.

  ex)
  // prettier: 'unused',
  lintRules: {
    // import: {},
  },
  

Sample

// index.js

module.exports = {
  // [prettier]
  // - "prettier.overrides"를 사용할 수 없으므로, .prettierrc 파일을 사용할 수 있도록
  //   아래와 같이 string 형태로 지정한다. 그래도 eslint-plugin-prettier 플러그인은 적용된다.
  //   >> prettier: '.prettierrc',
  prettier: {
    tabWidth: 2,
    useTabs: false,
  },
  lintRules: {
    general: {
      'comma-dangle': 'off',
      'no-console': 'off',
      'no-debugger': 'off',
    },
    typescript: {
      '@typescript-eslint/indent': ['error', 2],
    },
    react: {
      'react/jsx-boolean-value': 'off',
      'jsx-wrap-multilines': 'off', // might be specify no prefix
    },
    reactHooks: {
      'rules-of-hooks': 'error',
      'exhaustive-deps': 'warn',
    },
    next: {
      'no-img-element': 'off',
    },
    vue: {
      'attribute-hyphenation': 'off',
      'vue/html-closing-bracket-spacing': 'off',
      'vue/html-indent': ['error', 2],
      'html-self-closing': 'off',
    },
    nuxt: {
      'nuxt/no-cjs-in-config': 'off',
    },
    unicorn: {
      'escape-case': 'error',
    },
    promise: {
      'promise/valid-params': 'off',
    },
    import: {},
    jest: {},
    lintest: {
      report: [1, 'all', 10, 300], // @lintest/eslint-plugin 참고
    },
    node: {},
  },

  // disables .eslintignore usage
  disableLintIgnore: false,
  // turns on ESLint parserOptions.createDefaultProgram
  enableCompatibility: false,
}

Etcs

린트 퍼포먼스 향상을 위해 아래와 같이 performance report를 콘솔로 출력할 수 있다.
린트시 수행시간을 체크해보면서 시간이 많이 걸리는 룰에 대해 비활성화하면 수행속도 향상에 도움이 된다.

$ export TIMING=1
$ npm run lint

Change Log

프로젝트 변경사항은 CHANGELOG.md 파일 참조.

License

프로젝트 라이센스는 LICENSE 참조.