onboardmap

onboardmap

コードベースに参加する際に必要なのは、主に全体像を把握することです。プログラムはどこから始まるのか、テストはどこにあるのか、そのうち一つだけを実行するにはどうすればよいのか、特定の領域について誰に尋ねればよいのか。onboardmap は、すでに手元にある情報からそのマップを作成します。リポジトリのファイルパス、エントリーポイントと考えるパス、記録する場合はテストを実行するコマンド、各パスプレフィックスを担当する人またはチームの一覧を指定します。onboardmap が返すのは、そのマップです。領域ごとに分類されたファイル、実際に存在するエントリーポイント、指定したものの存在しないエントリーポイント、すべてのテストファイル、担当者のいないすべてのファイル、そして集計値が含まれます。リポジトリを開くことはありません。マップは、指定された情報だけから作成されます。

ファイルの領域はパスの最初のセグメントです。そのため、src/ の配下はすべて src 領域に属し、パスにスラッシュがないトップレベルのファイルは、文字どおり (root) という領域に属します。領域は昇順に並びます。各領域には、その領域に含まれるファイル数、そのうちテストファイルの数、指定した順に並んだ、その領域内のエントリーポイント、ファイルの担当者（重複を除き、ソート済み）が記載されます。

ファイルがテストファイルと見なされる条件は二つあります。ベース名（最後のスラッシュより後の部分）に .test. または .spec. が含まれている場合です。たとえば、parser.test.ts が該当します。または、ディレクトリセグメントのいずれかが test、tests、__tests__、spec のいずれかと完全に一致する場合です。たとえば、tests/helpers/setup.ts が該当します。testfoo.ts のように名前が t-e-s-t で始まるだけのファイルや、testing という名前のフォルダーは、どちらの条件にも一致しないため、テストファイルではありません。

担当者の割り当てには、最長一致ルールによるプレフィックスマッチングを使用します。ファイルとプレフィックスが等しい場合、プレフィックスがスラッシュで終わり、ファイルがそのプレフィックスで始まる場合、またはファイルがプレフィックスにスラッシュを加えた文字列で始まる場合、そのプレフィックスがファイルを担当します。たとえば、src は src/app.ts を担当しますが、srcfoo/app.ts は担当しません。二つのプレフィックスが一致する場合は、より長い方が優先されます。これにより、広いプレフィックスでツリー全体を担当しつつ、より狭いプレフィックスで特定のサブツリーを別の担当者に割り当てられます。どのプレフィックスにも一致しないファイルは、担当者なしとして一覧表示されます。

指定したエントリーポイントがファイル一覧に含まれていなくても、エラーにはなりません。新しく参加した人向けのマップを作るときこそ、文書に記載された開始地点が存在しないことを知りたいものです。見つかったエントリーポイントは指定した順に出力され、見つからなかったものは別に、指定した順で報告されます。集計値のエントリーポイント数に含まれるのは、見つかったものだけです。テストコマンドは、空文字列の場合も含め、一字一句そのまま出力されます。指定しなかった場合は null として報告されます。

不正な入力（ファイル一覧がない、空である、または配列でない場合、ファイルパスが文字列でない、または空の場合、不正なエントリーポイント一覧、テストコマンドが文字列でない場合、担当者マップのキーが空、または値が空か文字列でない場合）は、問題のあるパスを示す検証エラーとなり、部分的な結果は返されません。同じパスを持つファイルが二つある場合は、重複したパスを示すエラーになります。未知の追加フィールドは無視されます。

CLI

npx @reneturcios/onboardmap map --input args.json
npx @reneturcios/onboardmap --version

args.json には引数オブジェクト全体が含まれます。

{
  "files": [
    "README.md",
    "src/index.ts",
    "src/parser.ts",
    "src/parser.test.ts",
    "tests/helpers/setup.ts",
    "docs/guide.md"
  ],
  "entry_points": ["src/index.ts", "src/main.ts"],
  "test_command": "npm test",
  "owners": {
    "src": "alice",
    "docs": "bob"
  }
}

マップは JSON として出力されます。

{
  "areas": [
    {
      "area": "(root)",
      "files": 1,
      "tests": 0,
      "entry_points": [],
      "owners": []
    },
    {
      "area": "docs",
      "files": 1,
      "tests": 0,
      "entry_points": [],
      "owners": ["bob"]
    },
    {
      "area": "src",
      "files": 3,
      "tests": 1,
      "entry_points": ["src/index.ts"],
      "owners": ["alice"]
    },
    {
      "area": "tests",
      "files": 1,
      "tests": 1,
      "entry_points": [],
      "owners": []
    }
  ],
  "entry_points": ["src/index.ts"],
  "missing_entry_points": ["src/main.ts"],
  "test_files": ["src/parser.test.ts", "tests/helpers/setup.ts"],
  "unowned_files": ["README.md", "tests/helpers/setup.ts"],
  "test_command": "npm test",
  "counts": {
    "files": 6,
    "test_files": 2,
    "areas": 4,
    "entry_points": 1,
    "unowned": 2
  }
}

終了コード：成功時は 0、実行時エラー（読み取れない、または無効な入力ファイルや、不正な入力を含む）の場合は 1、使用方法のエラーの場合は 2 です。

MCP サーバー

npx -y @reneturcios/onboardmap mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "onboardmap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/onboardmap", "mcp"]
    }
  }
}

ツール

• build_onboard_map — 呼び出し元から提供されたリポジトリ情報をもとに、新規参加者向けマップを作成します。ファイルを領域別にグループ化し、エントリーポイント、テストの配置場所、担当者を示します。

  • files（文字列の配列、必須、1 項目以上）— リポジトリ内のファイルパス。リポジトリ相対で、呼び出し元が指定した順序
  • entry_points（文字列の配列、任意）— 呼び出し元がエントリーポイントとして指定するパス。省略した場合はありません
  • test_command（文字列、任意）— テストスイートを実行するコマンド。マップにそのまま記載されます
  • owners（オブジェクト、任意）— パスのプレフィックスから担当者名へのマップ。省略した場合、担当者はありません

  {areas, entry_points, missing_entry_points, test_files, unowned_files, test_command, counts} を返します。areas には、各領域につき 1 つの {area, files, tests, entry_points, owners} が含まれ、counts は {files, test_files, areas, entry_points, unowned} です。

Docker

docker run -i ghcr.io/cloudcorprecords/onboardmap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/onboardmap map --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios