ksk-design-system 1.55.0 → 1.57.0

package/AGENTS.md

@@ -33,6 +33,7 @@ UI を書く前に必ず確認すること:
 - [ ] アニメーションは `duration-[var(--Motion-Duration-*)]` / `ease-[var(--Motion-Easing-*)]` か（`duration-200` や生 `cubic-bezier` の直書きは禁止。トークン参照でないと `prefers-reduced-motion` の一括制御から漏れる）
 - [ ] 重なり順は `z-[var(--Z-*)]` か（`z-50` 一律だと Portal のマウント順で勝敗が決まる。`z-10` / `z-20` のコンポーネント内部の重なりは対象外。順序は DESIGN.md の Layering 節）
 - [ ] アイコンは `iconsax-reactjs` か（`lucide-react` / `heroicons` は使わない）
+- [ ] **選んだアイコンの「絵」を実際に見たか**。iconsax は名前と絵が一致しないものがある。`Check` は小切手（checkbook）でチェックマークではない（PR #349 で出荷直前まで残った）。チェックマークは `TickSquare` / `TickCircle`。また **"i" のグリフは iconsax に存在せず**、`InfoCircle` / `Information` / `Danger` / `Warning2` はすべて感嘆符「!」の器違いなので、情報アイコンは DS 自前の `InfoCircleIcon` を使う。名前で選んだら描画結果を目視し、意味が変わると困る箇所は path で固定するテストを書く <!-- docs-drift-ignore: Check TickSquare TickCircle InfoCircle Information Danger Warning2 InfoCircleIcon -->
 - [ ] 生タグ（`<button>` / `<input>` / `<a href>`）でなく DS コンポーネントを使ったか
 - [ ] CSS でベンダープレフィックス併記する場合、**`-webkit-` を先・標準形を後**に書いたか（消費側の minifier が同一プロパティとして dedupe し後勝ちのみ残すため。逆順だと Firefox で静かに無効化。`node scripts/check-prefix-order.mjs` が CI で検出）
 - [ ] flex 行（flex-col でない flex）で shrink-0 の兄弟と可変テキストを並べるとき、テキスト側に `flex-1`（+ 必要なら `min-w-[...]` 下限）を付けたか（`min-w-0` だけだと 1 文字ずつ折り返すまで潰れる。issue #293。`node scripts/check-flex-shrink.mjs` が CI で検出、例外は `ksk-lint-ignore KFX001 -- 理由`）
@@ -219,6 +220,7 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **src/components/COMPONENT_LOOKUP.md** | 全コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
 | **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
+| **contracts/deprecations.json** | 非推奨 API の正本台帳（移行先・削除予定。MIGRATION.md の一覧節と check-migration CLI の入力） |
 | **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
 
 ---
@@ -269,6 +271,12 @@ npm run generate:lookup
 # DESIGN.md contract 検査
 npm run lint:design
 
+# 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
+npm run lint:deprecations
+
+# MIGRATION.md の「非推奨 API 一覧」節を台帳から再生成
+npm run generate:migration-doc
+
 # @source safelist 再生成（新しい Tailwind クラスを使ったら実行）
 npm run generate:safelist
 

package/CLAUDE.md

@@ -33,6 +33,7 @@ UI を書く前に必ず確認すること:
 - [ ] アニメーションは `duration-[var(--Motion-Duration-*)]` / `ease-[var(--Motion-Easing-*)]` か（`duration-200` や生 `cubic-bezier` の直書きは禁止。トークン参照でないと `prefers-reduced-motion` の一括制御から漏れる）
 - [ ] 重なり順は `z-[var(--Z-*)]` か（`z-50` 一律だと Portal のマウント順で勝敗が決まる。`z-10` / `z-20` のコンポーネント内部の重なりは対象外。順序は DESIGN.md の Layering 節）
 - [ ] アイコンは `iconsax-reactjs` か（`lucide-react` / `heroicons` は使わない）
+- [ ] **選んだアイコンの「絵」を実際に見たか**。iconsax は名前と絵が一致しないものがある。`Check` は小切手（checkbook）でチェックマークではない（PR #349 で出荷直前まで残った）。チェックマークは `TickSquare` / `TickCircle`。また **"i" のグリフは iconsax に存在せず**、`InfoCircle` / `Information` / `Danger` / `Warning2` はすべて感嘆符「!」の器違いなので、情報アイコンは DS 自前の `InfoCircleIcon` を使う。名前で選んだら描画結果を目視し、意味が変わると困る箇所は path で固定するテストを書く <!-- docs-drift-ignore: Check TickSquare TickCircle InfoCircle Information Danger Warning2 InfoCircleIcon -->
 - [ ] 生タグ（`<button>` / `<input>` / `<a href>`）でなく DS コンポーネントを使ったか
 - [ ] CSS でベンダープレフィックス併記する場合、**`-webkit-` を先・標準形を後**に書いたか（消費側の minifier が同一プロパティとして dedupe し後勝ちのみ残すため。逆順だと Firefox で静かに無効化。`node scripts/check-prefix-order.mjs` が CI で検出）
 - [ ] flex 行（flex-col でない flex）で shrink-0 の兄弟と可変テキストを並べるとき、テキスト側に `flex-1`（+ 必要なら `min-w-[...]` 下限）を付けたか（`min-w-0` だけだと 1 文字ずつ折り返すまで潰れる。issue #293。`node scripts/check-flex-shrink.mjs` が CI で検出、例外は `ksk-lint-ignore KFX001 -- 理由`）
@@ -219,6 +220,7 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **src/components/COMPONENT_LOOKUP.md** | 全コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
 | **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
+| **contracts/deprecations.json** | 非推奨 API の正本台帳（移行先・削除予定。MIGRATION.md の一覧節と check-migration CLI の入力） |
 | **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
 
 ---
@@ -269,6 +271,12 @@ npm run generate:lookup
 # DESIGN.md contract 検査
 npm run lint:design
 
+# 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
+npm run lint:deprecations
+
+# MIGRATION.md の「非推奨 API 一覧」節を台帳から再生成
+npm run generate:migration-doc
+
 # @source safelist 再生成（新しい Tailwind クラスを使ったら実行）
 npm run generate:safelist
 

package/DESIGN.md

@@ -171,6 +171,10 @@ KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / nati
 影は5段（`--shadow-sm/md/lg/dialog/tooltip`）。面は md、浮く要素（dropdown/popover）は lg、
 モーダルは dialog。**境界は影＋1px罫線**で表現し、濃い影の多用は避ける。
 
+横スクロール中の固定列だけは方向付きの影を使う（`--shadow-sticky-inline-start` /
+`--shadow-sticky-inline-end`）。命名は論理方向で、inline-start = 行の先頭側に固定された列が
+末尾方向へ落とす影。生の `rgba()` を直書きせず、必ずこのトークンを参照する。
+
 ## Shapes
 
 角丸はトークン化（ベタ書き禁止）。**面 < モーダル < シート**の順で丸くなる。

package/MIGRATION.md

@@ -3,6 +3,40 @@
 メジャーバージョン間の移行ガイド。
 patch / minor は原則破壊変更なし、自動アップグレード可（例外: **v1.34.0 で npm パッケージ名を変更**。import の置換が必要。下記参照）。
 
+<!-- deprecations:start（自動生成・手で編集しない） -->
+
+## 非推奨 API 一覧
+
+正本は [`contracts/deprecations.json`](./contracts/deprecations.json)。この節はそこから生成しています。
+
+消費側での残存件数は次のコマンドで数えられます（read-only・残件があれば exit 1）:
+
+```bash
+npx ksk-ds check-migration ./src
+```
+
+| API | 使われ方 | 移行先 | 非推奨にした版 | 削除予定 |
+| --- | --- | --- | --- | --- |
+| `ListItem.interactive` | `<ListItem interactive>` | href または onClick を ListItem 自体へ渡す | 1.46.0 | v2.0.0 |
+| `ChipSelector.multiple` | `<ChipSelector multiple>` | selectionMode（multiple={false} は selectionMode="single"、multiple は selectionMode="multiple"） | unreleased | v2.0.0 |
+| `PillToggle.onValueChange` | `<PillToggle onValueChange>` | onChange | 1.49.0 | v2.0.0 |
+| `ProductCard.deliveryLabel` | `<ProductCard deliveryLabel>` | なし（v1.30.0 以降は描画されないため、渡している箇所は削除する） | 1.30.1 | v2.0.0 |
+| `Progress.tone` | `<Progress tone>` | variant | 1.40.1 | v2.0.0 |
+
+各エントリの補足:
+
+- **ListItem.interactive**（issue #207） — 外側の Link / button でラップする既存コードの視覚互換用に残している。 実装: src/components/patterns/list-item.tsx
+- **ChipSelector.multiple**（issue #352） — 既定が true（複数選択）で「渡し忘れると静かに壊れる側」に倒れているため新規実装では使わない。 実装: src/components/patterns/chip-selector.tsx / src/native/components/ChipSelector.tsx
+- **PillToggle.onValueChange**（issue #264） — 後方互換エイリアス。onChange を併せて渡した場合は onChange が優先される。 実装: src/components/ui/pill-toggle.tsx
+- **ProductCard.deliveryLabel** — 既存 consumer の型互換のためだけに残している no-op prop。 実装: src/components/patterns/commerce/product-card.tsx
+- **Progress.tone** — React Native 版のみ。既存 RN consumer 向けの互換。 実装: src/native/components/Progress.tsx
+
+削除は「全消費リポで `check-migration` の残件が 0」を条件に、`削除予定` のメジャーリリースで行います。
+
+<!-- deprecations:end -->
+
+---
+
 ## v2.0 (未リリース)
 
 まだメジャー破壊変更の予定はなし。
@@ -133,6 +167,15 @@ export default [
 
 これで codemod が拾えなかった旧 API の使用を検出できる。
 
+### Step 3.5. 非推奨 API の残存を数える
+
+```bash
+npx ksk-ds check-migration ./src
+```
+
+`contracts/deprecations.json` の非推奨 API が何件残っているかを、識別子別・ファイル別に出す
+（read-only・残件があれば exit 1 なので CI にも置ける）。
+
 ### Step 4. 動作確認
 
 ```bash

package/bin/check-migration.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+
+// ksk-ds check-migration
+// contracts/deprecations.json（正本台帳）に載っている非推奨 API が
+// consumer のソースにどれだけ残っているかを数える read-only CLI。
+//
+//   npx ksk-ds check-migration ./src
+//
+// 検出は TypeScript の AST で行う（正規表現ではない）。
+//   - kind=prop  : DS 由来のコンポーネントに付いた JSX 属性
+//   - kind=export: DS 由来の import 指定子 / re-export 指定子
+// コメント・文字列リテラル中の同名は AST 上そもそも識別子ではないため誤検出しない。
+//
+// 「DS 由来」の判定はローカル束縛を追う:
+//   1. ksk-design-system（旧名 @ksk/design-system・サブパス含む）からの import
+//   2. 相対 import 先のモジュールが DS からの re-export で同名を出している場合
+//      （移行期に consumer が置く互換バレルを取りこぼさないため。import だけでなく
+//        re-export も残件として数える、が要件）
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path"
+import ts from "typescript"
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"])
+const IGNORED_DIRECTORIES = new Set([
+  ".git",
+  ".next",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "storybook-static",
+])
+
+/** DS のパッケージ名（改名前も拾う）。サブパス import も対象。 */
+const DS_PACKAGE_RE = /^(?:ksk-design-system|@ksk\/design-system)(?:\/.*)?$/
+
+export function isDsSpecifier(specifier) {
+  return DS_PACKAGE_RE.test(specifier)
+}
+
+// ─── 台帳 ───────────────────────────────────────────────────
+
+export function loadDeprecations(pkgRoot) {
+  const ledgerPath = resolve(pkgRoot, "contracts/deprecations.json")
+  if (!existsSync(ledgerPath)) {
+    throw new Error(`contracts/deprecations.json が見つかりません: ${ledgerPath}`)
+  }
+  const ledger = JSON.parse(readFileSync(ledgerPath, "utf8"))
+  return ledger.deprecations ?? []
+}
+
+// ─── ファイル収集 ───────────────────────────────────────────
+
+export function collectSourceFiles(target) {
+  const results = []
+  const stat = statSync(target)
+  if (stat.isFile()) return SOURCE_EXTENSIONS.has(extname(target)) ? [target] : []
+
+  const stack = [target]
+  while (stack.length > 0) {
+    const current = stack.pop()
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue
+      const full = join(current, entry.name)
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) continue
+        stack.push(full)
+        continue
+      }
+      if (SOURCE_EXTENSIONS.has(extname(entry.name))) results.push(full)
+    }
+  }
+  return results.sort()
+}
+
+function parse(file, source) {
+  return ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, scriptKind(file))
+}
+
+function scriptKind(file) {
+  const ext = extname(file)
+  if (ext === ".tsx" || ext === ".jsx") return ts.ScriptKind.TSX
+  if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return ts.ScriptKind.JS
+  return ts.ScriptKind.TS
+}
+
+// ─── 相対 import の解決 ─────────────────────────────────────
+
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
+
+function resolveRelative(fromFile, specifier) {
+  const base = resolve(dirname(fromFile), specifier)
+  const stripped = base.replace(/\.(m|c)?jsx?$/, "")
+  const candidates = [
+    base,
+    ...RESOLVE_EXTENSIONS.map((ext) => `${stripped}${ext}`),
+    ...RESOLVE_EXTENSIONS.map((ext) => join(base, `index${ext}`)),
+  ]
+  for (const candidate of candidates) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
+  }
+  return null
+}
+
+// ─── モジュールごとの「DS 由来 re-export」解析 ──────────────
+
+/**
+ * ファイルが「その名前を DS 由来として外へ出している」かを判定できるようにする。
+ *
+ * 返り値:
+ *   { names: Set<string>, wildcardFromDs: boolean, wildcardRelative: string[] }
+ */
+function analyzeReExports(file, sourceFile) {
+  const names = new Set()
+  const relativeReExports = [] // { local: string|null, exported: string, from: string }
+  let wildcardFromDs = false
+  const wildcardRelative = []
+  const dsImportedLocals = new Map() // local 名 → 元の export 名（DS からの import）
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+      const spec = statement.moduleSpecifier.text
+      if (!isDsSpecifier(spec)) continue
+      const bindings = statement.importClause?.namedBindings
+      if (bindings && ts.isNamedImports(bindings)) {
+        for (const element of bindings.elements) {
+          dsImportedLocals.set(
+            element.name.text,
+            (element.propertyName ?? element.name).text,
+          )
+        }
+      }
+      continue
+    }
+
+    if (!ts.isExportDeclaration(statement)) continue
+    const spec =
+      statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)
+        ? statement.moduleSpecifier.text
+        : null
+
+    // export * from "..."
+    if (!statement.exportClause) {
+      if (spec && isDsSpecifier(spec)) wildcardFromDs = true
+      else if (spec && spec.startsWith(".")) wildcardRelative.push(spec)
+      continue
+    }
+    if (!ts.isNamedExports(statement.exportClause)) continue
+
+    for (const element of statement.exportClause.elements) {
+      const original = (element.propertyName ?? element.name).text
+      if (spec && isDsSpecifier(spec)) {
+        names.add(original)
+        names.add(element.name.text)
+      } else if (spec && spec.startsWith(".")) {
+        relativeReExports.push({ original, exported: element.name.text, from: spec })
+      } else if (!spec && dsImportedLocals.has(original)) {
+        // import { X } from "ksk-design-system"; export { X }
+        names.add(dsImportedLocals.get(original))
+        names.add(element.name.text)
+      }
+    }
+  }
+
+  return { file, names, wildcardFromDs, wildcardRelative, relativeReExports }
+}
+
+/**
+ * モジュールが name を DS 由来で re-export しているかを、相対経路を辿って判定する。
+ * 循環は visited で打ち切る。
+ */
+function reExportsFromDs(file, name, modules, visited = new Set()) {
+  if (visited.has(file)) return false
+  visited.add(file)
+  const info = modules.get(file)
+  if (!info) return false
+  if (info.wildcardFromDs) return true
+  if (info.names.has(name)) return true
+  for (const entry of info.relativeReExports) {
+    if (entry.exported !== name) continue
+    const target = resolveRelative(file, entry.from)
+    if (target && reExportsFromDs(target, entry.original, modules, visited)) return true
+  }
+  for (const spec of info.wildcardRelative) {
+    const target = resolveRelative(file, spec)
+    if (target && reExportsFromDs(target, name, modules, visited)) return true
+  }
+  return false
+}
+
+// ─── 1 ファイルの検査 ───────────────────────────────────────
+
+/**
+ * ファイル内の「DS 由来として束縛されたローカル名 → DS の export 名」を作る。
+ */
+function dsBindings(file, sourceFile, modules) {
+  const bindings = new Map()
+  const namespaces = new Set()
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue
+    const spec = statement.moduleSpecifier.text
+    const fromDs = isDsSpecifier(spec)
+    const relativeTarget = spec.startsWith(".") ? resolveRelative(file, spec) : null
+    if (!fromDs && !relativeTarget) continue
+
+    const clause = statement.importClause
+    if (!clause) continue
+    const named = clause.namedBindings
+
+    if (named && ts.isNamespaceImport(named)) {
+      if (fromDs) namespaces.add(named.name.text)
+      continue
+    }
+    if (named && ts.isNamedImports(named)) {
+      for (const element of named.elements) {
+        const original = (element.propertyName ?? element.name).text
+        if (fromDs) {
+          bindings.set(element.name.text, original)
+        } else if (relativeTarget && reExportsFromDs(relativeTarget, original, modules)) {
+          bindings.set(element.name.text, original)
+        }
+      }
+    }
+  }
+
+  return { bindings, namespaces }
+}
+
+/** `<Foo.Bar prop />` の基底名（Foo）と全体名を返す */
+function tagNames(tagName) {
+  if (ts.isIdentifier(tagName)) return { base: tagName.text, full: tagName.text }
+  if (ts.isPropertyAccessExpression(tagName)) {
+    let node = tagName
+    while (ts.isPropertyAccessExpression(node.expression)) node = node.expression
+    const base = ts.isIdentifier(node.expression) ? node.expression.text : null
+    return { base, full: tagName.getText() }
+  }
+  return { base: null, full: null }
+}
+
+function scanFile(file, sourceFile, deprecations, modules) {
+  const { bindings, namespaces } = dsBindings(file, sourceFile, modules)
+  const findings = []
+
+  const propEntries = deprecations.filter((d) => d.kind === "prop")
+  const exportEntries = deprecations.filter((d) => d.kind === "export")
+
+  const lineOf = (node) =>
+    sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1
+
+  // ── kind=prop: JSX 属性 ──────────────────────────────
+  const visitJsx = (node) => {
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const { base, full } = tagNames(node.tagName)
+      if (base) {
+        // Foo / DS.Foo のどちらでも、DS の export 名に解決した名前で照合する
+        let dsName = null
+        if (bindings.has(base) && full === base) dsName = bindings.get(base)
+        else if (namespaces.has(base) && full) dsName = full.slice(base.length + 1)
+
+        if (dsName) {
+          for (const attr of node.attributes.properties) {
+            if (!ts.isJsxAttribute(attr) || !ts.isIdentifier(attr.name)) continue
+            for (const entry of propEntries) {
+              if (entry.component !== dsName || entry.prop !== attr.name.text) continue
+              findings.push({ file, line: lineOf(attr), id: entry.id, usage: "prop", entry })
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visitJsx)
+  }
+  ts.forEachChild(sourceFile, visitJsx)
+
+  // ── kind=export: import / re-export ──────────────────
+  if (exportEntries.length > 0) {
+    const byIdentifier = new Map(exportEntries.map((e) => [e.identifier, e]))
+
+    for (const statement of sourceFile.statements) {
+      if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+        const spec = statement.moduleSpecifier.text
+        const relativeTarget = spec.startsWith(".") ? resolveRelative(file, spec) : null
+        if (!isDsSpecifier(spec) && !relativeTarget) continue
+        const named = statement.importClause?.namedBindings
+        if (!named || !ts.isNamedImports(named)) continue
+        for (const element of named.elements) {
+          const original = (element.propertyName ?? element.name).text
+          const entry = byIdentifier.get(original)
+          if (!entry) continue
+          if (
+            isDsSpecifier(spec) ||
+            (relativeTarget && reExportsFromDs(relativeTarget, original, modules))
+          ) {
+            findings.push({ file, line: lineOf(element), id: entry.id, usage: "import", entry })
+          }
+        }
+        continue
+      }
+
+      if (!ts.isExportDeclaration(statement)) continue
+      const spec =
+        statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)
+          ? statement.moduleSpecifier.text
+          : null
+      if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue
+      for (const element of statement.exportClause.elements) {
+        const original = (element.propertyName ?? element.name).text
+        const entry = byIdentifier.get(original)
+        if (!entry) continue
+        const relativeTarget = spec && spec.startsWith(".") ? resolveRelative(file, spec) : null
+        const fromDs =
+          (spec && isDsSpecifier(spec)) ||
+          (relativeTarget && reExportsFromDs(relativeTarget, original, modules)) ||
+          (!spec && bindings.has(original))
+        if (fromDs) {
+          findings.push({ file, line: lineOf(element), id: entry.id, usage: "re-export", entry })
+        }
+      }
+    }
+  }
+
+  return findings
+}
+
+// ─── 検査本体 ───────────────────────────────────────────────
+
+/**
+ * @returns {{ total: number, findings: Array, byIdentifier: Array<{id, count, replacement, removeIn}>, byFile: Array<{file, count}>, filesScanned: number }}
+ */
+export function checkMigration(target, deprecations, { cwd = process.cwd() } = {}) {
+  const files = collectSourceFiles(target)
+  const parsed = new Map()
+  const modules = new Map()
+
+  for (const file of files) {
+    const sourceFile = parse(file, readFileSync(file, "utf8"))
+    parsed.set(file, sourceFile)
+    modules.set(file, analyzeReExports(file, sourceFile))
+  }
+
+  const findings = []
+  for (const file of files) {
+    findings.push(...scanFile(file, parsed.get(file), deprecations, modules))
+  }
+
+  const counts = new Map()
+  for (const finding of findings) {
+    counts.set(finding.id, (counts.get(finding.id) ?? 0) + 1)
+  }
+  const byIdentifier = deprecations
+    .filter((d) => counts.has(d.id))
+    .map((d) => ({
+      id: d.id,
+      count: counts.get(d.id),
+      replacement: d.replacement,
+      removeIn: d.removeIn,
+    }))
+    .sort((a, b) => b.count - a.count || a.id.localeCompare(b.id))
+
+  const fileCounts = new Map()
+  for (const finding of findings) {
+    const rel = displayPath(finding.file, cwd)
+    fileCounts.set(rel, (fileCounts.get(rel) ?? 0) + 1)
+  }
+  const byFile = [...fileCounts.entries()]
+    .map(([file, count]) => ({ file, count }))
+    .sort((a, b) => b.count - a.count || a.file.localeCompare(b.file))
+
+  return {
+    total: findings.length,
+    findings,
+    byIdentifier,
+    byFile,
+    filesScanned: files.length,
+  }
+}
+
+function displayPath(file, cwd) {
+  const rel = relative(cwd, file)
+  return rel.startsWith("..") || isAbsolute(rel) ? file : rel
+}
+
+// ─── CLI ────────────────────────────────────────────────────
+
+export function runCheckMigrationCli(
+  argv,
+  { cwd = process.cwd(), pkgRoot = resolve("."), deprecations } = {},
+) {
+  const options = parseArgs(argv)
+  if (options.help) {
+    printHelp()
+    return 0
+  }
+
+  const target = resolve(cwd, options.target)
+  if (!existsSync(target)) {
+    console.error(`検査対象が見つかりません: ${target}`)
+    return 1
+  }
+
+  let entries
+  try {
+    entries = deprecations ?? loadDeprecations(pkgRoot)
+  } catch (error) {
+    console.error(String(error.message ?? error))
+    return 1
+  }
+
+  const result = checkMigration(target, entries, { cwd })
+
+  if (options.format === "json") {
+    console.log(
+      JSON.stringify(
+        {
+          total: result.total,
+          filesScanned: result.filesScanned,
+          byIdentifier: result.byIdentifier,
+          byFile: result.byFile,
+          findings: result.findings.map((f) => ({
+            file: displayPath(f.file, cwd),
+            line: f.line,
+            id: f.id,
+            usage: f.usage,
+          })),
+        },
+        null,
+        2,
+      ),
+    )
+    return result.total > 0 ? 1 : 0
+  }
+
+  printFindings(result, entries, cwd)
+  return result.total > 0 ? 1 : 0
+}
+
+function parseArgs(argv) {
+  let help = false
+  let format = "text"
+  let target = "./src"
+
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") {
+      help = true
+      continue
+    }
+    if (arg === "--format=json" || arg === "--json") {
+      format = "json"
+      continue
+    }
+    if (!arg.startsWith("-")) target = arg
+  }
+
+  return { help, format, target }
+}
+
+function printFindings(result, entries, cwd) {
+  if (result.total === 0) {
+    console.log(
+      `ksk-ds check-migration: 非推奨 API の残存はありません（${result.filesScanned} files / 台帳 ${entries.length} 件）`,
+    )
+    return
+  }
+
+  console.log(
+    `ksk-ds check-migration: 非推奨 API の残存を ${result.total} 件検出しました（${result.filesScanned} files）`,
+  )
+
+  console.log(`\n識別子別:`)
+  for (const item of result.byIdentifier) {
+    console.log(`  ${String(item.count).padStart(4)}  ${item.id}`)
+    console.log(`        → ${item.replacement}（v${item.removeIn} で削除予定）`)
+  }
+
+  console.log(`\nファイル別:`)
+  for (const item of result.byFile) {
+    console.log(`  ${String(item.count).padStart(4)}  ${item.file}`)
+  }
+
+  console.log(`\n検出箇所:`)
+  for (const finding of result.findings) {
+    console.log(`  ${displayPath(finding.file, cwd)}:${finding.line} ${finding.id} (${finding.usage})`)
+  }
+
+  console.log(`\n移行手順は MIGRATION.md の「非推奨 API 一覧」節を参照してください。`)
+  console.log(`残件が 0 になったバージョンで DS 側の互換コードを削除できます。`)
+}
+
+function printHelp() {
+  console.log(`ksk-ds check-migration
+
+使い方:
+  ksk-ds check-migration [DIR]
+  ksk-ds check-migration [DIR] --format=json
+
+DIR の既定値:
+  ./src
+
+動作:
+  contracts/deprecations.json の非推奨 API が DIR 配下に残っていないかを
+  TypeScript の AST で数えます（コメント・文字列は誤検出しません）。
+  DS からの import に加え、相対 import 経由の re-export も残件として数えます。
+  完全 read-only。残件があれば終了コード 1（CI で使えます）。
+`)
+}
+
+const invokedDirectly =
+  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)
+
+if (invokedDirectly) {
+  const pkgRoot = resolve(dirname(new URL(import.meta.url).pathname), "..")
+  process.exit(runCheckMigrationCli(process.argv.slice(2), { cwd: process.cwd(), pkgRoot }))
+}

package/bin/init.js

@@ -42,6 +42,7 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   npx ksk-ds lint src --format json   CI 向け JSON 出力
   npx ksk-ds lint --changed           Git 差分のみ検査
   npx ksk-ds check-migration ./src    非推奨 API の残存を検査（read-only）
+  npx ksk-ds check-migration ./src --format=json  CI 向け JSON 出力
   npx ksk-ds check-duplicates [DIR]    DS と同名のローカル実装を検査
   npx ksk-ds check-duplicates --strict 検出時に exit 1（CI 向け）
   npx ksk-ds codemod                   利用できる codemod を一覧
@@ -58,8 +59,8 @@ if (cmd === "lint") {
 }
 
 if (cmd === "check-migration") {
-  const { runCheckMigrationCli } = await import("../scripts/codemod/check-migration.mjs")
-  const status = runCheckMigrationCli(args.slice(1))
+  const { runCheckMigrationCli } = await import("./check-migration.js")
+  const status = runCheckMigrationCli(args.slice(1), { cwd: process.cwd(), pkgRoot })
   process.exit(status)
 }