development-javascript

name	development-javascript
description	TRIGGER when: creating or editing .ts/.js/.mts/.mjs files, creating Node.js CLI tools, or modifying package.json. Enforces coding style, module conventions, package.json standards, and Node.js CLI tool patterns.

General Guidelines (must)

• classを利用した設計を避ける
  • 関数とオブジェクトリテラルを組み合わせたモジュールパターンを利用する
• import/requireは相対パスを利用する
• import/requireでindexを省略しない
• Array.prototype.forEachの利用を禁じる
  • for...ofやforループを利用する

Style Guidelines (should)

• " より ' を優先して利用する
• 文末のセミコロンは省略する
• 関数定義はarrow functionよりnormal functionを優先する
  • filter, map, reduceなどのcallback関数はarrow functionを利用する
• arrow functionを利用する場合は改行, {}, return を省略せずに記述する

上記スタイルをすべて満たす例:

function listActiveNames(users: User[]) {
  const active = users.filter((user) => {
    return user.active
  })
  return active.map((user) => {
    return user.name
  })
}

Environment Variables

• process.env を各所で参照することを禁じる
• 環境変数は config.ts または config.js からのみ読み取る
• 他のモジュールは config を import して値を参照する

Scripting

• 使い捨てのスクリプトを作成・実行する場合は最新バージョンのNode.jsを利用する
• 一時的な自動化でもPythonやBashでの実装を禁じる

npm Guidelines

• .npmrcをプロジェクトルートに配置し、必要に応じて以下の設定を記述する
  • min-release-age=7 を記述してリリース後すぐのバージョンを避ける

# .npmrc
min-release-age=7

Dockerfile内でnpmを利用する場合は、npm install の前に .npmrc をコピーして設定を反映させる. また、.npmrcのビルド忘れを防ぐために min-release-age だけはDockerfileのnpm installコマンドにも直接渡す.

RUN npm install --min-release-age=7

package.json Guidelines

• はじめてpackage.jsonを作成する場合は下記のみで構成する
  • private: true と type: "module" のみを記述
  • name, main, version, author, license, description, keywords は用いない

{
  "private": true,
  "type": "module"
}

Test Guidelines

• describe を利用しない。test をファイルのルートレベルに記述する
• テストをグルーピングしたい場合は describe ではなくテストファイル自体を分離する
• グローバル setup ファイル (setup.ts / globalSetup 等) でモジュールをモック化しない
  • グローバルモックは依存関係を不可視にし、特定テストで実物が必要になった際の解除 (unmock) が複雑化する
  • モックが必要なテストファイルに vi.mock(...) 等の mock を記述して局所化する
  • 同じモックを複数ファイルで使う場合は、共通の mock factory を関数として export し各テストファイルから呼び出す
• DBや外部リソースを共有するテスト同士の干渉を防ぐため「並列耐性」のある形で記述する
  • 同一ファイル内で固有のprefixを共有することを禁じる。テスト毎に task.id などのtestごとに unique となる値を prefix として利用し、seed を分離する
  • beforeAll で共通の seed データを作成することを禁じる。beforeAll は接続と必要最小限の truncate のみに留め、seed は各テスト内で task.id prefix を付けて作成する
  • 共有リソース全体に依存する assertion (例: count, length) を禁じる。find() 等で自テストが作成したレコードのみを対象に assertion する
  • pagination 等のため大量データ (例: PAGE_SIZE 超え) を投入することを禁じる。境界値テストは別途専用環境が必要なら省略するか、件数に依存しない代替検証 (skip が効くか) で代用する
• サンプルとNGパターンは references/tests.md を参照

TypeScript Guidelines

• Prefer type over interface
• type assertion を禁じる
• 既に存在する型は再定義せず推論で導出し再定義を禁じる（対象を限らずすべての型に適用）
  • 詳細は references/type-inference.md を参照
• functionの返り値は指定せず推論に任せる
• baseUrlを利用しない
• 可能な場合は必ず as const を記述する
• any 型の利用を禁じる
  • やむをえない場合は unknown 型を利用し、type guardで型を絞り込む
  • 外部ライブラリの型定義が不完全な場合のみ、コメントで理由を明記した上で使用を許可する
• TypeScriptファイルを直接実行する場合はNode.jsのstrip-typesを利用する
  • ts-node, tsx の利用を禁じる
  • ref: https://nodejs.org/docs/api/typescript.html
• Array.prototype.filterではできる限り型推論に任せ is を利用しない

Node.js CLI Tool Guidelines

Node.js CLIツールを作成する場合は以下に従う。

• ファイルの先頭に #!/usr/bin/env node を付与する
• 引数解析は node:util から parseArgs をインポートして利用し、手書きパーサは避ける
  • commander などの利用は禁じる
• TypeScriptで記述し、Node.jsのstrip-typesで実行する

CLI用 package.json Template

bin は strip-types で直接実行する .ts ファイルを指す（.js へのビルドは行わない）。

{
  "private": true,
  "type": "module",
  "bin": {
    "my-cli": "./bin/cli.ts"
  }
}

CLI Entry Point Template (bin/cli.ts)

#!/usr/bin/env node
import { parseArgs } from 'node:util'

const { values, positionals } = parseArgs({
  options: {
    help: {
      type: 'boolean',
      short: 'h',
      default: false,
    }
  },
  allowPositionals: true,
})

function showHelp() {
  console.log(`Usage: my-cli <command> [options]

Options:
  -h, --help  Show this help message`)
}

async function main() {
  if (values.help) {
    showHelp()
    return
  }
  // ここにメイン処理を実装する
}

main().catch((err) => {
  console.error(err)
  process.exitCode = 1
})

CLI用 tsconfig.json Template

{
  "compilerOptions": {
    "incremental": true,
    "strict": true,
    "outDir": "dist",
    "sourceMap": true,
    "esModuleInterop": true,
    "target": "esnext",
    "module": "nodenext",
    "skipLibCheck": true,
    "noUncheckedIndexedAccess": true,
    "noEmit": true,
    "allowImportingTsExtensions": true
  }
}

Mandatory Skill Enforcement

• このskillがloadされたら、変更した .ts / .js ファイルを完了前に再読し、このskillの禁止事項に違反していないか必ず確認すること
• skill違反が見つかった場合、その時点で未完了として扱い、説明や完了報告より先に修正すること