ls-lint

ls-lint v2.3

バージョンに関する注意: このスキルは ls-lint v2.3 専用のドキュメントです。先に進む前に、インストールされているバージョンが一致していることを確認してください。

ls-lint --version
# or
npx @ls-lint/ls-lint --version

別のバージョンがインストールされている場合は、作業を中止し、https://ls-lint.org または GitHub リポジトリ https://github.com/loeffel-io/ls-lint にある、そのバージョンの公式ドキュメントを参照してください。バージョンによって設定構文や利用可能なルールが異なる場合があります。

プロジェクトのファイルシステム全体にわたって命名規則を適用する、非常に高速なディレクトリおよびファイル名リンターです。

公式リソース:

• GitHub: https://github.com/loeffel-io/ls-lint
• ドキュメント: https://ls-lint.org/2.3/getting-started/introduction.html

主な機能:

• 数千個のファイルを数ミリ秒で処理
• .ls-lint.yml による最小限の設定
• クロスプラットフォーム対応：Windows、macOS、Linux
• Unicode を完全サポート
• 依存関係を最小限に抑制（go-yaml、doublestar）

インストール

# NPM (recommended)
npm install -D @ls-lint/ls-lint

# NPX (no install)
npx @ls-lint/ls-lint

# Homebrew (macOS/Linux)
brew install ls-lint

# Direct download (Linux amd64)
curl -sL -o ls-lint https://github.com/loeffel-io/ls-lint/releases/download/v2.3.1/ls-lint-linux-amd64
chmod +x ls-lint

設定の基本

プロジェクトのルートに .ls-lint.yml を作成し、主に次の 2 つのセクションを設定します。

ls:
  # Rules for directories and file extensions
  .js: kebab-case
  .ts: kebab-case

ignore:
  # Paths to exclude from linting
  - .git
  - node_modules

ls-lint の実行

# Run with default config (.ls-lint.yml)
npx @ls-lint/ls-lint

# Custom config path
ls-lint --config path/to/.ls-lint.yml

# Custom working directory
ls-lint --workdir /path/to/project

組み込みルール

6 種類の命名規則ルールを利用できます。

ルール	説明	例
lowercase	すべて小文字。文字以外は無視します	readme、test
camelCase	camelCase。文字と数字のみ	myFile
PascalCase	PascalCase。文字と数字のみ	MyComponent
snake_case	小文字とアンダースコア	my_file
SCREAMING_SNAKE_CASE	大文字とアンダースコア	MY_CONSTANT
kebab-case	小文字とハイフン	my-file

ルールの組み合わせ

パイプ演算子 | を使うと、複数の規則を許可できます。

ls:
  .ts: camelCase | PascalCase   # Either is valid
  .js: kebab-case | snake_case

拡張子とサブ拡張子

標準拡張子

特定のファイル形式にルールを適用します。

ls:
  .js: kebab-case
  .ts: kebab-case
  .json: kebab-case
  .md: SCREAMING_SNAKE_CASE   # README.md, CHANGELOG.md

サブ拡張子

.d.ts、.test.js、.module.css などの複合拡張子を処理します。

ls:
  .d.ts: kebab-case           # Type definition files
  .test.ts: kebab-case        # Test files
  .module.css: kebab-case     # CSS modules
  .config.js: kebab-case      # Config files

ワイルドカード拡張子

.* を使うと、すべての拡張子に一致します。

ls:
  .*: kebab-case              # All files must be kebab-case

ディレクトリ名

.dir を使うと、ディレクトリ名の規則を適用できます。

ls:
  .dir: kebab-case            # All directories must be kebab-case

パスパターン

グローバルルール

最上位に指定したルールは、プロジェクト全体に適用されます。

ls:
  .js: kebab-case             # Applies everywhere
  .ts: kebab-case

ignore:
  - node_modules

ディレクトリ固有のルール

特定のディレクトリに対してグローバルルールを上書きします。

ls:
  .js: kebab-case             # Global default

  components:                 # Override for components/
    .js: PascalCase

  src/models:                 # Override for src/models/
    .js: PascalCase

ディレクトリルールは、指定したディレクトリとそのすべてのサブディレクトリに適用されます。

Glob パターン

柔軟にパスを指定するには、ワイルドカードを使用します。

ls:
  # Single wildcard: matches one directory level
  packages/*/src:
    .ts: kebab-case

  # Double wildcard: matches any depth
  packages/**/components:
    .tsx: PascalCase

パターンの選択肢

中かっこを使うと、複数の選択肢を指定できます。

ls:
  packages/*/{src,tests}:
    .ts: kebab-case

  src/{components,pages}:
    .tsx: PascalCase

高度なルール

正規表現パターン

独自の命名パターンを指定するには、regex:^pattern$ 形式で正規表現を使用します。

ls:
  # Files must start with uppercase letter
  .ts: regex:^[A-Z].*$

  # Allow files starting with underscore or letter
  .js: regex:^[_a-z][a-zA-Z0-9]*$

正規表現を組み込みルールと組み合わせます。

ls:
  .ts: PascalCase | regex:^index$   # PascalCase OR "index"

ディレクトリ置換

パターン内で親ディレクトリの名前を参照します。

ls:
  # File must match parent directory name
  components/*/:
    .tsx: regex:^${0}$   # ${0} = parent directory name

存在ルール

ファイル数の制約を適用します。

ls:
  # Exactly one index file required
  src/:
    index.ts: exists:1

  # Between 1-5 test files allowed
  tests/:
    .test.ts: exists:1-5

  # No image files allowed
  src/:
    .png: exists:0
    .jpg: exists:0

命名ルールと組み合わせます。

ls:
  .ts: kebab-case | exists:1   # Must be kebab-case AND exactly one

よくある設定

JavaScript／TypeScript プロジェクト

ls:
  .dir: kebab-case
  .js: kebab-case
  .ts: kebab-case
  .tsx: PascalCase           # React components
  .d.ts: kebab-case
  .json: kebab-case
  .md: SCREAMING_SNAKE_CASE

  src/components:
    .tsx: PascalCase

ignore:
  - .git
  - node_modules
  - dist
  - coverage

モノレポのパターン

ls:
  .dir: kebab-case
  .*: kebab-case

  packages/*/src:
    .ts: kebab-case
    .tsx: PascalCase

  packages/*/{src,tests}:
    .dir: kebab-case

ignore:
  - .git
  - node_modules
  - "**/dist"
  - "**/coverage"
  - "**/build"

GitHub Actions との連携

基本的なワークフロー設定：

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]

jobs:
  ls-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ls-lint/action@v2

アクション設定オプション

- uses: ls-lint/action@v2
  with:
    config: .ls-lint.yml          # Config file path
    workdir: .                    # Working directory
    error-output-format: text     # text or json
    warn: false                   # Output to stdout, exit 0
    debug: false                  # Enable debug output

トラブルシューティング

よくある問題

ファイルが一致しない：パスパターンが実際のディレクトリ構成に一致していることを確認してください。

ルールが適用されない：より具体的なルールによって上書きされていないか確認してください。

ignore が機能しない：ignore パターンで正しい Glob 構文を使用していることを確認してください。

デバッグモード

詳細な出力を有効にして実行し、問題を診断します。

ls-lint --debug

外部リソース

このスキルで扱っていない機能については、以下を参照してください。

• GitHub リポジトリ: https://github.com/loeffel-io/ls-lint
• 公式ドキュメント: https://ls-lint.org/2.3/getting-started/introduction.html
• GitHub Action: https://github.com/ls-lint/action

公式ドキュメントでは、以下のような追加機能について説明しています。

• 複数の設定ファイル
• Bazel との統合
• Docker の使用方法
• 正規表現の構文全体