axmap-cli 0.0.1

package/tools/cluster-experiment.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * 실험 1 — 폴더 정답표와 미래 공변경 중 어느 쪽이 진짜인가.
+ *
+ *   node tools/cluster-experiment.mjs --list repos.txt --out result.jsonl [--work /tmp/exp]
+ *
+ * 🔴 이 실험이 답해야 하는 질문은 하나다.
+ *
+ *    **군집이 폴더보다 나은가?**
+ *
+ * D17 은 "폴더가 다른데 실제로 얽혀 있는 것을 찾는 것이 목적" 이라고 적었다.
+ * 그런데 axMap 자기 자신에서 재보니 미래적중 순위와 폴더일치 순위의 상관이
+ * 0.906 이었다 — 미래를 잘 맞히는 설정이 곧 폴더와 잘 맞는 설정이었다.
+ * 저장소 하나로는 "정리가 잘 된 저장소라서" 인지 "채점기가 폴더를 재고 있어서"
+ * 인지 구별할 수 없다. 그래서 여럿에 건다.
+ *
+ * ── 기준선 셋을 함께 낸다 ────────────────────────────────────────────────
+ *
+ * 군집의 미래적중률만 내면 그 숫자가 높은지 낮은지 알 수가 없다. 비교 대상이
+ * 없으면 45% 가 훌륭한 건지 형편없는 건지 말할 수 없기 때문이다.
+ *
+ *   dir1·dir2·dir3  디렉터리를 깊이별로 나눈 분할. **이걸 못 이기면 군집을
+ *                   할 이유가 없다.** 깊이를 셋 다 내는 것은 폴더 쪽을
+ *                   최대한 세우기 위해서다
+ *   shuffled        블록 크기 분포는 그대로 두고 배정만 섞은 것
+ *
+ * 그리고 셋을 **lift = 적중률 ÷ 섞었을 때의 적중률** 로 환산해 비교한다.
+ * 적중률을 날것으로 비교하면 굵은 분할이 무조건 이기기 때문이다.
+ *
+ * 🔴 기준선을 약하게 잡으면 아무 의미가 없다. 폴더 쪽을 이길 수 있게 만들어
+ *    놓고 이겼다고 하는 것은 우리 자신을 속이는 것이다.
+ */
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { build, scan } from '../app/lib/analyze.mjs'
+import { coChange, readCommitSets } from '../app/lib/cochange.mjs'
+import { buildGraph, cluster, rng } from '../corpus/cluster.mjs'
+import { ari, containment, directoryPartition, shape } from '../corpus/clusterscore.mjs'
+
+const argv = process.argv.slice(2)
+const flag = (n, d) => { const i = argv.indexOf(`--${n}`); return i >= 0 && argv[i + 1] ? argv[i + 1] : d }
+
+const LIST = flag('list', null)
+const OUT = flag('out', 'cluster-exp.jsonl')
+const WORK = flag('work', path.join(os.tmpdir(), 'axmap-cluster-exp'))
+const HOLDOUT = Number(flag('holdout', '0.2'))
+const SEEDS = Number(flag('seeds', '3'))
+const MAX_FILES = Number(flag('max-files', '3000'))
+
+if (!LIST) { console.error('--list 이 필요하다 (한 줄에 owner/name 또는 git 주소)'); process.exit(1) }
+
+// 격자는 좁게. 이 실험의 질문은 "어느 설정이 최고인가" 가 아니라
+// "군집이 폴더를 이기는가" 이므로, 순위상관을 낼 만큼만 있으면 된다.
+const GRID = {
+  algorithm: ['leiden', 'louvain'],
+  objective: ['modularity', 'cpm'],
+  resolution: [0.25, 0.5, 0.75, 1, 1.5, 2],
+  coWeight: [0, 1],
+}
+
+const say = (s) => process.stderr.write(`${new Date().toISOString().slice(11, 19)} ${s}\n`)
+const git = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1 << 28 })
+
+// ---------------------------------------------------------------------------
+
+function rankOf(v) {
+  const idx = v.map((x, k) => [x, k]).sort((a, b) => a[0] - b[0])
+  const out = new Array(v.length)
+  for (let k = 0; k < idx.length;) {
+    let j = k
+    while (j + 1 < idx.length && idx[j + 1][0] === idx[k][0]) j++
+    const r = (k + j) / 2 + 1
+    for (let m = k; m <= j; m++) out[idx[m][1]] = r
+    k = j + 1
+  }
+  return out
+}
+
+function spearman(a, b) {
+  const p = []
+  for (let i = 0; i < a.length; i++) if (Number.isFinite(a[i]) && Number.isFinite(b[i])) p.push([a[i], b[i]])
+  if (p.length < 8) return null
+  const ra = rankOf(p.map((x) => x[0])), rb = rankOf(p.map((x) => x[1]))
+  const n = p.length, m = (n + 1) / 2
+  let num = 0, da = 0, db = 0
+  for (let k = 0; k < n; k++) { const x = ra[k] - m, y = rb[k] - m; num += x * y; da += x * x; db += y * y }
+  if (!da || !db) return null
+  return num / Math.sqrt(da * db)
+}
+
+/**
+ * 블록 크기 분포는 그대로 두고 배정만 섞는다.
+ *
+ * 🔴 이 기준선이 없으면 속는다. 블록이 크면 그 안에 떨어지는 쌍이 자동으로
+ *    많아진다 — 구조를 못 찾아도 적중률이 오른다. 크기 효과를 뺀 나머지가
+ *    진짜로 찾아낸 몫이다.
+ */
+function shuffledLike(membership, seed) {
+  const rand = rng(seed)
+  const out = Int32Array.from(membership)
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = (rand() * (i + 1)) | 0
+    const t = out[i]; out[i] = out[j]; out[j] = t
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+
+function measure(dir, name) {
+  const files = scan(dir, { maxFiles: MAX_FILES })
+  const graph = build(files)
+  const ids = graph.nodes.map((n) => n.id)
+  if (ids.length < 40) return { name, skip: `파일 ${ids.length}개` }
+
+  const raw = readCommitSets(dir)
+  if (!raw || raw.length < 80) return { name, skip: `커밋 ${raw?.length ?? 0}개` }
+
+  const cut = Math.max(15, Math.floor(raw.length * HOLDOUT))
+  const withCov = (a) => { a.coverage = raw.coverage; return a }
+  const futureSets = withCov(raw.slice(0, cut))
+  const pastSets = withCov(raw.slice(cut))
+
+  const nodeIds = new Set(ids)
+  const tag = (e) => e.map((x) => ({ ...x, origin: 'cochange' }))
+  const pastCo = tag(coChange(dir, nodeIds, { raw: pastSets, minSupport: 2 })?.edges ?? [])
+  const futureCo = tag(coChange(dir, nodeIds, { raw: futureSets, minSupport: 1 })?.edges ?? [])
+  if (futureCo.length < 30) return { name, skip: `미래 공변경 ${futureCo.length}쌍` }
+
+  // ── 기준선 ──────────────────────────────────────────────────────────────
+  /**
+   * 🔴 적중률을 그대로 비교하면 **무조건 굵은 분할이 이긴다.**
+   *
+   * 블록이 크면 그 안에 떨어지는 쌍이 자동으로 많아진다. 실제로 첫 실행에서
+   * "폴더 100%" 가 나왔는데, 그건 폴더 하나가 전부를 삼켜서 모든 쌍이
+   * 자동으로 안에 들어간 것이었다 — 아무것도 안 맞힌 것이 만점으로 보였다.
+   *
+   * 그래서 모든 분할에 대해 **같은 크기 분포로 섞은 대조군**을 함께 낸다.
+   *
+   *   lift = 적중률 ÷ 섞었을 때의 적중률
+   *
+   * lift 1.0 은 "크기 때문에 맞은 것일 뿐 구조는 못 찾았다" 는 뜻이다.
+   * 이 값이라야 블록 5개짜리와 40개짜리를 같은 자로 잴 수 있다.
+   */
+  const withBase = (m) => {
+    const hit = containment(ids, futureCo, m).weighted
+    const sh = containment(ids, futureCo, shuffledLike(m, 99)).weighted
+    return { ...shape(m), weighted: hit, shuffled: sh, lift: sh ? hit / sh : null }
+  }
+  const dirs = { 1: directoryPartition(ids, { depth: 1 }), 2: directoryPartition(ids, { depth: 2 }), 3: directoryPartition(ids, { depth: 3 }) }
+  const base = { dir1: withBase(dirs[1]), dir2: withBase(dirs[2]), dir3: withBase(dirs[3]) }
+
+  // ── 격자 ────────────────────────────────────────────────────────────────
+  const cands = []
+  for (const coWeight of GRID.coWeight) {
+    const g = buildGraph(ids, [...graph.edges, ...pastCo], { coWeight, minSupport: 2 })
+    for (const algorithm of GRID.algorithm) {
+      for (const objective of GRID.objective) {
+        for (const resolution of GRID.resolution) {
+          const runs = []
+          for (let s = 1; s <= SEEDS; s++) runs.push(cluster(algorithm, g, { resolution, objective, seed: s }).membership)
+          const m = runs[0]
+          const sh = shape(m)
+          let stab = 0, np = 0
+          for (let i = 0; i < runs.length; i++) for (let j = i + 1; j < runs.length; j++) {
+            const v = ari(runs[i], runs[j]); if (v != null) { stab += v; np++ }
+          }
+          cands.push({
+            label: `${algorithm}/${objective} γ=${resolution} co=${coWeight}`,
+            algorithm, objective, resolution, coWeight,
+            blocks: sh.usableBlocks, maxShare: sh.maxShare, singletonShare: sh.singletonShare,
+            stability: np ? stab / np : null,
+            ariDir1: ari(m, dirs[1]),
+            ariDir2: ari(m, dirs[2]),
+            heldOut: containment(ids, futureCo, m).weighted,
+            // 같은 크기 분포로 섞은 것. 구조가 아니라 크기로 맞는 몫.
+            heldOutShuffled: containment(ids, futureCo, shuffledLike(m, 99)).weighted,
+          })
+        }
+      }
+    }
+  }
+
+  for (const c of cands) c.lift = c.heldOutShuffled ? c.heldOut / c.heldOutShuffled : null
+  const usable = cands.filter((c) => c.heldOut != null)
+  const best = [...usable].sort((a, b) => b.heldOut - a.heldOut)[0] ?? null
+  // 얼룩(한 블록이 다 삼킨 것)을 뺀 뒤의 최고. 이쪽이 실제로 쓸 수 있는 답이다.
+  const bestSane = [...usable].filter((c) => c.maxShare <= 0.4 && c.blocks >= 3)
+    .sort((a, b) => b.heldOut - a.heldOut)[0] ?? null
+
+  return {
+    name,
+    files: ids.length,
+    staticEdges: graph.edges.length,
+    commits: { past: pastSets.length, future: futureSets.length },
+    coEdges: { past: pastCo.length, future: futureCo.length },
+    parseCoverage: graph.nodes.filter((n) => n.parsed).length / ids.length,
+    base,
+    best,
+    bestSane,
+    // 🔴 실험의 핵심 숫자
+    rankCorr: {
+      heldOutVsDir1: spearman(usable.map((c) => c.heldOut), usable.map((c) => c.ariDir1)),
+      heldOutVsDir2: spearman(usable.map((c) => c.heldOut), usable.map((c) => c.ariDir2)),
+      heldOutVsStability: spearman(usable.map((c) => c.heldOut), usable.map((c) => c.stability)),
+      heldOutVsBlocks: spearman(usable.map((c) => c.heldOut), usable.map((c) => c.blocks)),
+    },
+    candidates: cands,
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+const repos = fs.readFileSync(LIST, 'utf8').split('\n').map((s) => s.trim()).filter((s) => s && !s.startsWith('#'))
+fs.mkdirSync(WORK, { recursive: true })
+say(`저장소 ${repos.length}개 · 격자 ${GRID.algorithm.length * GRID.objective.length * GRID.resolution.length * GRID.coWeight.length}칸 · 씨앗 ${SEEDS}`)
+
+let ok = 0, skipped = 0, failed = 0
+for (const [i, entry] of repos.entries()) {
+  const url = entry.includes('://') || entry.startsWith('git@') ? entry : `https://github.com/${entry}.git`
+  const safe = entry.replace(/[^\w.-]/g, '_')
+  const dir = path.join(WORK, safe)
+  const t0 = Date.now()
+  try {
+    if (!fs.existsSync(path.join(dir, '.git'))) {
+      fs.rmSync(dir, { recursive: true, force: true })
+      // 🔴 blob:none — 필요한 것은 커밋 이력이지 파일 내용의 모든 판본이 아니다.
+      //    다만 작업 트리는 필요하므로 얕은(shallow) 클론은 쓰지 않는다.
+      git(['clone', '-q', '--filter=blob:none', url, dir])
+    }
+    const r = measure(dir, entry)
+    r.at = new Date().toISOString()
+    r.ms = Date.now() - t0
+    fs.appendFileSync(OUT, `${JSON.stringify(r)}\n`)
+    if (r.skip) { skipped++; say(`  [${i + 1}/${repos.length}] 건너뜀 ${entry} — ${r.skip}`) }
+    else {
+      ok++
+      const b = r.bestSane ?? r.best
+      const dirBest = Math.max(r.base.dir1.lift ?? 0, r.base.dir2.lift ?? 0, r.base.dir3.lift ?? 0)
+      say(`  [${i + 1}/${repos.length}] ${entry} 파일 ${r.files} · lift 군집 ${b?.lift?.toFixed(2)}`
+        + ` vs 폴더 ${dirBest.toFixed(2)}`
+        + ` · 순위상관 ${r.rankCorr.heldOutVsDir1?.toFixed(2) ?? '—'} (${((Date.now() - t0) / 1000).toFixed(0)}초)`)
+    }
+  } catch (e) {
+    failed++
+    fs.appendFileSync(OUT, `${JSON.stringify({ name: entry, error: String(e.message).slice(0, 300), at: new Date().toISOString() })}\n`)
+    say(`  [${i + 1}/${repos.length}] 실패 ${entry} — ${String(e.message).slice(0, 120)}`)
+  } finally {
+    // 재고 나서 즉시 지운다. 안 지우면 디스크가 먼저 죽는다 (docs/SSOT.md 와 같은 이유).
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+}
+say(`끝. 성공 ${ok} · 건너뜀 ${skipped} · 실패 ${failed} → ${OUT}`)

package/tools/cluster-sweep.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * 저장소 하나에서 군집 하이퍼파라미터를 쓸어본다 — 미래를 떼어놓고 채점한다.
+ *
+ *   node tools/cluster-sweep.mjs <저장소경로> [--out out.json]
+ *   node tools/cluster-sweep.mjs . --holdout 0.25 --seeds 5
+ *
+ * 🔴 이 도구의 전부는 **커밋 이력을 앞뒤로 자르는 한 줄**이다.
+ *
+ * 앞쪽(오래된 쪽) 커밋만으로 공변경을 만들어 블록을 나누고, 뒤쪽(최근) 커밋에서
+ * 실제로 같이 바뀐 쌍을 그 블록이 품고 있었는지 센다. 만든 데 쓴 엣지로 채점하면
+ * 무조건 잘 맞는다 — 그건 채점이 아니라 동어반복이다.
+ *
+ * docs/SSOT.md 가 "떼어놓고 검증(held-out)하지 않았다. 이것이 있어야 기준이
+ * 관찰에서 검증된 지침이 된다" 를 못 한 일로 적어 두었다. 여기가 그 고리다.
+ *
+ * ⚠️ 아직 코퍼스에 연결하지 않았다. 저장소 하나에서 이 값들이 말이 되는지
+ *    먼저 눈으로 보고 나서 `corpus/measure.mjs` 에 붙인다. 검증 안 된 계측을
+ *    16,876개에 먼저 거는 것은 순서가 거꾸로다.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { build, scan } from '../app/lib/analyze.mjs'
+import { coChange, readCommitSets } from '../app/lib/cochange.mjs'
+import { buildGraph, cluster } from '../corpus/cluster.mjs'
+import {
+  agreement, ari, containment, directoryPartition, rank, shape,
+} from '../corpus/clusterscore.mjs'
+
+// ---------------------------------------------------------------------------
+// 인자
+// ---------------------------------------------------------------------------
+
+const argv = process.argv.slice(2)
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`)
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : def
+}
+const root = argv.find((a) => !a.startsWith('--') && argv[argv.indexOf(a) - 1]?.startsWith('--') !== true)
+  ?? argv[0]
+
+if (!root || root.startsWith('--')) {
+  console.error('사용법: node tools/cluster-sweep.mjs <저장소경로> [--out out.json] [--holdout 0.2] [--seeds 4]')
+  process.exit(1)
+}
+
+const HOLDOUT = Number(flag('holdout', '0.2'))
+const SEEDS = Number(flag('seeds', '4'))
+const OUT = flag('out', null)
+const MAX_FILES = Number(flag('max-files', '4000'))
+
+// 쓸어볼 격자. 넓이가 먼저다 — 좁게 깊이 파면 다른 조합이 더 나았는지 영영 모른다.
+const GRID = {
+  algorithm: (flag('algos', 'leiden,louvain,labelprop')).split(','),
+  objective: (flag('objectives', 'modularity,cpm')).split(','),
+  resolution: (flag('gammas', '0.25,0.5,0.75,1,1.5,2,3')).split(',').map(Number),
+  coWeight: (flag('coweights', '0,0.5,1,2')).split(',').map(Number),
+}
+
+// ---------------------------------------------------------------------------
+// 재료
+// ---------------------------------------------------------------------------
+
+const t0 = Date.now()
+const say = (s) => process.stderr.write(`${s}\n`)
+
+say(`저장소 ${path.resolve(root)}`)
+const files = scan(root, { maxFiles: MAX_FILES })
+const graph = build(files)
+const ids = graph.nodes.map((n) => n.id)
+const nodeIds = new Set(ids)
+say(`파일 ${ids.length}개 · 정적 엣지 ${graph.edges.length}개`)
+
+if (ids.length < 20) {
+  say('파일이 20개도 안 된다 — 군집을 말할 그래프가 아니다.')
+  process.exit(1)
+}
+
+/**
+ * 커밋을 앞뒤로 자른다.
+ *
+ * `readCommitSets` 는 **최신이 먼저**다 (git log 순서). 그래서 앞쪽 slice 가
+ * 미래고 뒤쪽 slice 가 과거다 — 직관과 반대이므로 이름을 분명히 붙인다.
+ */
+const raw = readCommitSets(root)
+if (!raw || raw.length < 50) {
+  say(`커밋이 ${raw?.length ?? 0}개뿐이다 — 떼어놓을 미래가 없다.`)
+  process.exit(1)
+}
+const cut = Math.max(10, Math.floor(raw.length * HOLDOUT))
+const withCoverage = (arr) => { arr.coverage = raw.coverage; return arr }
+const futureSets = withCoverage(raw.slice(0, cut))
+const pastSets = withCoverage(raw.slice(cut))
+say(`커밋 ${raw.length}개 → 과거 ${pastSets.length} / 미래 ${futureSets.length} (holdout ${HOLDOUT})`)
+
+/**
+ * 🔴 origin 을 여기서 붙인다. `coChange().edges` 에는 없다 — 붙이는 것은
+ *    `overlayEdges` 인데 우리는 그걸 안 거치기 때문이다. 안 붙이면
+ *    `buildGraph` 가 거부한다 (전에는 조용히 정적 엣지로 삼켰다).
+ */
+const tag = (edges) => edges.map((e) => ({ ...e, origin: 'cochange' }))
+
+const pastCo = tag(coChange(root, nodeIds, { raw: pastSets, minSupport: 2 })?.edges ?? [])
+const futureCo = tag(coChange(root, nodeIds, { raw: futureSets, minSupport: 1 })?.edges ?? [])
+say(`공변경 엣지 — 과거 ${pastCo.length} · 미래(채점용) ${futureCo.length}`)
+
+if (futureCo.length < 20) {
+  say('미래 공변경이 20쌍도 안 된다 — 채점할 수 없다. holdout 을 늘려보라.')
+  process.exit(1)
+}
+
+const dirTruth = directoryPartition(ids, { depth: 1 })
+
+// ---------------------------------------------------------------------------
+// 쓸기
+// ---------------------------------------------------------------------------
+
+const candidates = []
+let done = 0
+const total = GRID.algorithm.length * GRID.objective.length * GRID.resolution.length * GRID.coWeight.length
+
+for (const coWeight of GRID.coWeight) {
+  // 공변경 무게가 바뀌면 그래프 자체가 바뀐다. 격자 바깥에서 한 번만 만든다.
+  const g = buildGraph(ids, [...graph.edges, ...pastCo], { coWeight, minSupport: 2 })
+
+  for (const algorithm of GRID.algorithm) {
+    for (const objective of GRID.objective) {
+      for (const resolution of GRID.resolution) {
+        // label propagation 은 파라미터가 없다. 격자를 돌면 같은 답을 수십 번 낸다.
+        if (algorithm === 'labelprop' && (objective !== GRID.objective[0] || resolution !== GRID.resolution[0])) {
+          done++
+          continue
+        }
+
+        const runs = []
+        for (let s = 1; s <= SEEDS; s++) {
+          runs.push(cluster(algorithm, g, { resolution, objective, seed: s }).membership)
+        }
+        const m = runs[0]
+        const sh = shape(m)
+
+        candidates.push({
+          label: `${algorithm}/${objective} γ=${resolution} co=${coWeight}`,
+          algorithm,
+          objective,
+          resolution,
+          coWeight,
+          shape: sh,
+          stability: agreement(runs),
+          dirAgreement: ari(m, dirTruth),
+          // 🔴 만든 데 안 쓴 엣지로만 잰다
+          heldOut: containment(ids, futureCo, m),
+          // 대조군: 만든 데 쓴 엣지로 재면 얼마나 나오나. 둘의 차이가 곧 과적합이다.
+          inSample: containment(ids, pastCo, m),
+        })
+
+        if (++done % 10 === 0) say(`  ${done}/${total}`)
+      }
+    }
+  }
+}
+
+const result = rank(candidates)
+
+// ---------------------------------------------------------------------------
+// 내기
+// ---------------------------------------------------------------------------
+
+const pct = (v) => (v == null ? '  —  ' : `${(v * 100).toFixed(1)}%`.padStart(6))
+const num = (v) => (v == null ? ' —  ' : v.toFixed(2))
+
+console.log(`\n저장소  ${path.resolve(root)}`)
+console.log(`파일 ${ids.length} · 정적엣지 ${graph.edges.length} · 과거커밋 ${pastSets.length} · 미래커밋 ${futureSets.length}`)
+console.log(`후보 ${candidates.length}개 중 제약 통과 ${result.passed.length}개\n`)
+
+console.log('상위 12 (제약 통과분, 미래 공변경 적중률 순)')
+console.log('  ' + '조합'.padEnd(34) + '블록'.padEnd(6) + '최대'.padEnd(7) + '안정'.padEnd(7)
+  + '폴더'.padEnd(7) + '미래'.padEnd(8) + '과거')
+for (const c of result.passed.slice(0, 12)) {
+  console.log('  ' + c.label.padEnd(34)
+    + String(c.shape.usableBlocks).padEnd(6)
+    + pct(c.shape.maxShare).padEnd(7)
+    + num(c.stability.mean).padEnd(7)
+    + num(c.dirAgreement).padEnd(7)
+    + pct(c.heldOut.weighted).padEnd(8)
+    + pct(c.inSample.weighted))
+}
+
+if (!result.best) {
+  console.log(`\n고르지 못했다: ${result.why}`)
+  // 왜 다 떨어졌는지 사유를 세어 보여준다. 빈 답만 주면 다음 사람이 격자를 헤맨다.
+  const tally = new Map()
+  for (const c of result.judged) for (const f of c.fail) {
+    const kind = f.replace(/[\d.]+/g, 'N')
+    tally.set(kind, (tally.get(kind) ?? 0) + 1)
+  }
+  console.log('\n탈락 사유')
+  for (const [why, n] of [...tally].sort((a, b) => b[1] - a[1])) console.log(`  ${String(n).padStart(4)}회  ${why}`)
+} else {
+  const b = result.best
+  console.log(`\n고른 것  ${b.label}`)
+  console.log(`  블록 ${b.shape.usableBlocks}개 · 최대 블록 ${pct(b.shape.maxShare)} · 혼자 ${pct(b.shape.singletonShare)}`)
+  console.log(`  안정성 평균 ${num(b.stability.mean)} / 최악 ${num(b.stability.min)}`)
+  console.log(`  폴더와의 일치 ${num(b.dirAgreement)}  (낮을수록 폴더가 모르는 것을 찾았다는 뜻)`)
+  console.log(`  미래 공변경 적중 ${pct(b.heldOut.weighted)} · 같은 것을 과거로 재면 ${pct(b.inSample.weighted)}`)
+  const gap = (b.inSample.weighted ?? 0) - (b.heldOut.weighted ?? 0)
+  console.log(`  과적합 폭 ${pct(gap)}  (클수록 과거에만 맞는 분할이다)`)
+}
+
+if (OUT) {
+  fs.writeFileSync(OUT, JSON.stringify({
+    root: path.resolve(root),
+    at: new Date().toISOString(),
+    files: ids.length,
+    staticEdges: graph.edges.length,
+    commits: { past: pastSets.length, future: futureSets.length, holdout: HOLDOUT },
+    seeds: SEEDS,
+    grid: GRID,
+    best: result.best?.label ?? null,
+    why: result.why,
+    candidates: result.judged,
+  }, null, 1))
+  say(`\n적었다: ${OUT}`)
+}
+say(`${((Date.now() - t0) / 1000).toFixed(1)}초`)

package/tools/make-icon.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * 앱 아이콘(`desktop/build/icon.ico`)을 코드로 그린다.
+ *
+ * 🔴 왜 그림 파일을 안 싣는가.
+ *
+ * 저장소에 바이너리를 넣지 않으면 리뷰에서 내용이 보이고, 크기나 색을 고치는 데
+ * 이미지 편집기가 필요 없다. 모양도 이 앱의 은유 그대로다 — 가운데 시작점과
+ * 그것을 두르는 궤도(`graph.js` 의 `SHELL_GAP` 이 그리는 고리).
+ * 트레이 아이콘(`desktop/main.mjs` 의 `trayIcon`)과 같은 도형이다.
+ *
+ * 🔴 ICO 포맷에서 두 번 밟는 곳.
+ *
+ *   ① 픽셀은 **BGRA** 이고 행은 **아래에서 위로** 쌓인다. RGBA 로 채우면 빨강과
+ *      파랑이 바뀌고, 위에서 아래로 쌓으면 상하가 뒤집힌 채 조용히 뜬다
+ *   ② 헤더의 `biHeight` 는 **높이의 두 배**다. XOR 비트맵과 AND 마스크를 함께
+ *      담기 때문이다. 32비트라 마스크는 안 쓰지만 **자리는 반드시 있어야** 한다
+ *
+ *   $ node tools/make-icon.mjs
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const OUT = path.join(ROOT, 'desktop', 'build', 'icon.ico')
+
+/** 여러 크기를 담는다. 작업 표시줄은 작은 것을, 바탕화면은 큰 것을 고른다. */
+const SIZES = [16, 32, 48, 64, 128, 256]
+
+/** shell.css 의 `--accent` 와 같은 값. 한쪽만 고치면 아이콘과 화면이 어긋난다. */
+const INK = [217, 119, 87]
+
+/** 반지름 `at` 에 두께 `half` 로 부드러운 획을 놓는다. */
+const band = (d, at, half) => Math.max(0, Math.min(1, 1 - Math.abs(d - at) / half))
+
+/** 한 크기의 XOR 비트맵(BGRA · 아래에서 위로). */
+function pixels(s) {
+  const buf = Buffer.alloc(s * s * 4)
+  const c = (s - 1) / 2
+  const ring = s * 0.36
+  const stroke = Math.max(1, s * 0.055)
+  const dot = Math.max(0.8, s * 0.055)
+
+  for (let y = 0; y < s; y++) {
+    for (let x = 0; x < s; x++) {
+      const d = Math.hypot(x - c, y - c)
+      const a = Math.min(1, band(d, ring, stroke) + band(d, 0, dot))
+      if (a <= 0.004) continue
+      // 아래에서 위로 쌓는다 — 안 그러면 상하가 뒤집힌 채 조용히 뜬다
+      const i = ((s - 1 - y) * s + x) * 4
+      buf[i] = INK[2]      // B
+      buf[i + 1] = INK[1]  // G
+      buf[i + 2] = INK[0]  // R
+      buf[i + 3] = Math.round(255 * a)
+    }
+  }
+  return buf
+}
+
+/** BITMAPINFOHEADER + XOR + AND 마스크. */
+function image(s) {
+  const head = Buffer.alloc(40)
+  head.writeUInt32LE(40, 0)      // biSize
+  head.writeInt32LE(s, 4)        // biWidth
+  head.writeInt32LE(s * 2, 8)    // 🔴 biHeight — XOR 과 AND 를 합친 높이다
+  head.writeUInt16LE(1, 12)      // biPlanes
+  head.writeUInt16LE(32, 14)     // biBitCount
+  head.writeUInt32LE(0, 16)      // biCompression = BI_RGB
+
+  // 32비트는 알파를 쓰므로 마스크는 0(불투명)으로 두되 자리는 있어야 한다.
+  const maskRow = Math.ceil(s / 32) * 4
+  const mask = Buffer.alloc(maskRow * s)
+
+  return Buffer.concat([head, pixels(s), mask])
+}
+
+function ico(sizes) {
+  const imgs = sizes.map(image)
+  const dir = Buffer.alloc(6)
+  dir.writeUInt16LE(0, 0)              // reserved
+  dir.writeUInt16LE(1, 2)              // type = icon
+  dir.writeUInt16LE(sizes.length, 4)
+
+  let offset = 6 + sizes.length * 16
+  const entries = sizes.map((s, i) => {
+    const e = Buffer.alloc(16)
+    // 256 은 0 으로 적는다 — 한 바이트에 안 들어간다
+    e.writeUInt8(s >= 256 ? 0 : s, 0)
+    e.writeUInt8(s >= 256 ? 0 : s, 1)
+    e.writeUInt8(0, 2)                 // 팔레트 없음
+    e.writeUInt8(0, 3)
+    e.writeUInt16LE(1, 4)              // planes
+    e.writeUInt16LE(32, 6)             // bitCount
+    e.writeUInt32LE(imgs[i].length, 8)
+    e.writeUInt32LE(offset, 12)
+    offset += imgs[i].length
+    return e
+  })
+
+  return Buffer.concat([dir, ...entries, ...imgs])
+}
+
+fs.mkdirSync(path.dirname(OUT), { recursive: true })
+const buf = ico(SIZES)
+fs.writeFileSync(OUT, buf)
+console.log(`아이콘 ${path.relative(ROOT, OUT)} · ${SIZES.join('·')}px · ${buf.length.toLocaleString()} bytes`)