dupscan (書く前に引く・セルフレビューで写しを寄せる)

dupscan (実体は dotfiles の bin/dupscan。PATH 上にあるので、どの repo でもそのまま呼べる) は Swift と Go のメソッド (関数・メソッド・クロージャ) を構文木で読む。調べる repo には何も書かない。 詳しい使い方と限界は ~/dotfiles/src/dupscan/README.md、検出の方法は ~/dotfiles/docs/dupscan-detection.md。

1. 書く前に引く (気軽に)

写しが生まれやすいもの (ヘルパー・初期化・値を組み立てる関数・テストの fixture) を書く前に、同じものが既にないかを 1 回引く。 全部の定義の前に引く必要はない。上位 20 件を 1 行ずつ返す (DualNoteApp の 1130 単位で 0.5 秒。初回だけ build に時間がかかる)。

dupscan index -returns StorageLocation        # 作ろうとしている値の型 (戻り値の型の一部)
dupscan index -name location                  # 名前の候補の一部
dupscan index -param-type ConnectionID        # 受け取る型
dupscan index -doc bucket                     # doc comment の語 (最初の行だけ)
dupscan evidence bucket                       # 上で見つからないとき: doc の全文・テスト・ソースの行にある語から、doc の付いた宣言と、その語の行で呼ばれている名前を出す

使えるものがあれば使う (repo が .dupscan.json の shared に書いた共通の置き場所の定義は [shared] と出て先に並ぶ。 他のファイルから使えないものは [private] か [fileprivate]、Go の別の package から使えない小文字の関数は [unexported] と出る。使うなら共通の置き場所へ寄せる)。無ければ書く。

2. 調べもの (grep の前に)

Swift の定義・参照を探すときは grep より先にこちらを使う。構文木から引くので、コメント・文字列・呼び出し側の行が混ざらず、返る量が少ない (LSP の「定義へ移動」「参照を検索」の代わり。Swift の 4 repo の 7 日で grep 2,882 回に対し dupscan 13 回だった。issue 921)。 文字列・コメント・設定ファイルを探すなら grep のほうが向く。Swift の repo でシンボルを grep すると、hook がこの節のコマンドを 1 行案内する。

dupscan def StorageClient                     # 定義を本体つきで (型は宣言とメンバーの一覧: protocol の要件・格納 property・enum の case を含む)
dupscan def StorageClient.upload              # 型を絞る (generic の引数と where 句は外して照合する)。make(x:_:) で引数ラベルも絞れる
dupscan refs StorageClient                    # 参照の一覧 ([型の位置] / [式の位置] と、それを囲む関数)。宣言名・引数名・局所の束縛・ラベルは数えない
dupscan callers 'make(x:_:)'                  # 呼び出しの箇所と、それを囲む関数 (名前だけでも引ける)
dupscan context StorageClient.upload          # 変更の前に: 上の def・refs・callers を 1 回の走査でまとめて (text だけ。参照・呼び出しは名前だけで当てる)
dupscan index -file Sources/Foo.swift         # このファイルに何があるか (outline)

型を解決しないので、同名の別の定義・参照も当たる (近似)。flag は名前・パスの前に書く。 def / refs / context は Swift だけを読む (Go のファイルを読まなかったことは stderr に出る)。Go の定義・参照は LSP (gopls) で引く。 callers と index -file は Go のファイルにも使える (Go に引数ラベルは無いので、callers は名前と引数の数で当てる)。 Claudeの既存grep案内hookは、Goを明示した検索には index -name / callers を案内する。hook自身は解析/buildを起こさず、GoとSwiftの通知間隔を分ける。Codexで同hookが自動発火することは未検証。

3. セルフレビューで gate を回す

実装が終わったら、commit の前に回す。repo が make test や CI に gate を組み込んでいれば同じ判定がそこでも走るので、先に回せば手戻りが減る (組み込んでいない repo では、ここで回すのが唯一の確かめ)。

dupscan gate                    # upstream との merge-base から作業ツリーまでに増えた写し。無ければ 1 行で rc=0

• rc=1 (違反): 「新しい」に出た単位を、「同じ形」に出た既存の単位へ寄せる (呼び出しに置き換える・共通の置き場所へ移す)。寄せる前に 4 節で境界を確かめる。寄せてからもう一度回す
• 誤検知・意図して分けている写し: 寄せずに除外を書く。単位の直前に // dupscan:allow <false-positive|intentional> <理由>、 組なら違反の -v に出る「除外の 1 行」に kind と reason を埋めて repo の root の .dupscan.json に貼る。 除外を書いたら、ユーザーへの報告に書く (除外は gate を緩めるので、人の目に届けるのが唯一の歯止め。gate の 1 行目にも「新しく足された除外」と出る)
• rc=2 (判定不能): base が決まらない (upstream が無い) なら -base origin/master のように渡す
• 1 つの関数について「同じ形のものがあるか・なぜ同じと判定したか」は dupscan near <file>:<関数名> / dupscan explain <file>:<関数名>

4. 寄せる前に境界を確かめる (ドメインを混ぜない)

dupscan が見るのは本体の形だけで、ドメインの境界は見ない。同じ形でも同じ規則とは限らない。gate の違反を寄せるときも、 report の既存の組をまとめて統合するときも、1 組ずつ次を確かめてから寄せる (ユーザー指示 2026-10-25)。

• 同じ規則か、偶然同じ形か: 「片方の仕様が変わったら、もう片方も同じく変わるべきか」を問う。yes なら寄せる。 no (provider ごとの規約・層ごとの責務がたまたま同じ書き方になっている) なら寄せず、intentional と理由を書いて除外する
• 寄せ先はその概念の持ち主に置く: 使う側のどれもが既に依存してよい層・モジュールのうち、その規則を持つ所に置く。 寄せるために、別のドメインの知識 (特定の provider の規約・上の層の型) を共通の層へ持ち込まない。依存の向きを逆にしない
• 何でも入る置き場所を作らない: Util / Helper / Common のような、ドメインの語で名前の付かない置き場所に寄せない。 寄せた先の型・関数の名前をドメインの語で付けられないなら、境界をまたいでいる兆候として寄せ方を考え直す
• 寄せない判断も成果。除外の理由には「どのドメインのどの規則が、なぜ別に変わりうるか」を書く (形が違うから、では書かない)