axmap-cli 0.0.1

package/tools/smoke.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * 화면이 실제로 뜨는지 본다.
+ *
+ * 🔴 `npm test` 는 화면이 죽어도 초록이다.
+ *
+ * 하룻밤에 두 번 겪었다. 둘 다 문법은 멀쩡했고 테스트는 전부 통과했는데
+ * 브라우저에서는 아무것도 안 떴다.
+ *
+ *   1. 주석에 쓴 `examples/[별]/main.go` 의 `[별]/` 가 블록 주석을 닫아 파일이 깨졌다
+ *   2. `let urlReady` 를 첫 사용처보다 아래에 선언해 TDZ 참조 에러가 났고,
+ *      그 예외가 부트스트랩 체인을 끊어 흐름·걸음·탭이 통째로 죽었다
+ *
+ * 2번이 특히 나빴다. 나는 `?step=3` 으로만 확인했는데 그 경로는 크래시 지점을
+ * 우회한다. **되는 길만 보면 안 되는 길은 영원히 안 보인다.**
+ *
+ * 그래서 여기서는 사람이 실제로 처음 여는 주소 — **맨 주소** 를 연다.
+ * 자바스크립트가 다 돌고 난 DOM 에 부트스트랩이 남긴 흔적이 있는지만 본다.
+ * 픽셀은 안 본다. 스크린샷 비교는 깨지기 쉽고, 우리가 잡으려는 것은
+ * "화면이 통째로 안 뜨는 것" 이지 "3px 밀린 것" 이 아니다.
+ *
+ * 의존성은 늘리지 않는다. 이미 깔린 Chrome 을 `--dump-dom` 으로 부른다.
+ */
+
+import { spawn, spawnSync, execFileSync } from 'node:child_process'
+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 PORT = Number(process.env.AXMAP_SMOKE_PORT ?? 7912)
+/** 검사 대상은 이 저장소 자신이다. 늘 있고, 크지 않고, 결과가 안정적이다. */
+const TARGET = process.argv[2] ?? ROOT
+
+/** 이미 깔린 Chrome 을 찾는다. 없으면 **건너뛰지 않고 실패한다** — 검사는 돌아야 검사다. */
+function findChrome() {
+  if (process.env.CHROME && fs.existsSync(process.env.CHROME)) return process.env.CHROME
+  const cands = process.platform === 'win32'
+    ? [
+        'C:/Program Files/Google/Chrome/Application/chrome.exe',
+        'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+        path.join(process.env.LOCALAPPDATA ?? '', 'Google/Chrome/Application/chrome.exe'),
+      ]
+    : ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+       '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome']
+  for (const c of cands) { try { if (fs.existsSync(c)) return c } catch { /* 다음 후보 */ } }
+  return null
+}
+
+/**
+ * 새 껍데기(`/`)가 남겨야 하는 흔적.
+ *
+ * `data-shell="ready"` 는 `init()` 의 맨 끝에서 붙는다. 그 앞에 API 세 번
+ * (`/api/agents` · `/api/graph` · `/api/sessions`)이 있으므로 이 한 줄이
+ * **모듈 · 서버 라우트 · 세션 저장소**를 한꺼번에 증명한다.
+ */
+/**
+ * 처음 오는 사람이 보는 화면(`/`).
+ *
+ * `data-shell="ready"` 는 `init()` 의 맨 끝에서 붙는다. 그 앞에 API 세 번
+ * (`/api/agents` · `/api/version` · `/api/sessions`)이 있으므로 이 한 줄이
+ * **모듈 · 서버 라우트 · 세션 저장소**를 한꺼번에 증명한다.
+ */
+const FIRST = [
+  { what: '부트스트랩(shell.js)', re: /data-shell="ready"/ },
+  { what: '3분할 · 왼쪽 목록', re: /id="chats"/ },
+  { what: '3분할 · 가운데', re: /id="stage"/ },
+  { what: '3분할 · 오른쪽 입력', re: /id="composer"/ },
+  { what: '모드 탭(감시·이해)', re: /data-mode="watch"/ },
+  { what: '툴바(아이콘)', re: /data-menu="all"/ },
+  /**
+   * 🔴 처음 오는 사람에게 보이는 CLI 고르기 카드.
+   * 정적 HTML 에 없다 — `/api/agents` 를 받아 `drawPicks()` 가 그린다.
+   * 이 표식이 **온보딩이 실제로 떴다**와 **CLI 감지가 돈다**를 함께 증명한다.
+   */
+  { what: '처음 설정 · CLI 고르기', re: /class="pick/ },
+]
+
+/**
+ * 고르기를 끝낸 사람이 보는 화면(`/?agent=…`).
+ *
+ * 🔴 온보딩이 가운데 칸을 가리므로, 주소로 고른 값을 심지 않으면 렌더러가
+ * 검사에서 통째로 빠진다. 헤드리스는 클릭을 못 한다.
+ *
+ * `data-path` 와 `class="wires"` 는 정적 HTML 에 없다 — `/api/ladder` 를 받아
+ * `stage.js` 가 만든다. 둘이 **겹 계산 · 라우트 · 카드 · 버스 연결선**을 덮는다.
+ */
+const OPENED = [
+  { what: '부트스트랩(shell.js)', re: /data-shell="ready"/ },
+  { what: '가운데 · 번호 카드', re: /data-path="/ },
+  { what: '가운데 · 버스 연결선', re: /class="wires"/ },
+  { what: '온보딩이 닫혔다', re: /id="onboard" hidden/ },
+]
+
+const PAGES = [
+  { path: '/', what: '처음 오는 사람', must: FIRST },
+  { path: '/?agent=claude', what: '고르기를 끝낸 사람', must: OPENED },
+]
+
+async function waitUp(ms = 120_000) {
+  const until = Date.now() + ms
+  while (Date.now() < until) {
+    try {
+      await fetch(`http://127.0.0.1:${PORT}/`, { signal: AbortSignal.timeout(2000) })
+      return true
+    } catch { await new Promise((r) => setTimeout(r, 400)) }
+  }
+  return false
+}
+
+const chrome = findChrome()
+if (!chrome) {
+  console.error('Chrome 을 찾지 못했습니다. CHROME=<경로> 로 알려주세요.')
+  console.error('건너뛰지 않습니다 — 안 도는 검사는 검사가 아닙니다.')
+  process.exit(1)
+}
+
+// 이미 그 포트를 쓰고 있으면 그것을 재사용하지 않는다. 무엇을 검사했는지가 흐려진다.
+const log = path.join(ROOT, '.axmap-smoke.log')
+const out = fs.openSync(log, 'w')
+const server = spawn(process.execPath, [path.join(ROOT, 'app', 'server.mjs'), TARGET, String(PORT)],
+  { cwd: ROOT, stdio: ['ignore', out, out], windowsHide: true })
+
+let failed = 0
+try {
+  if (!await waitUp()) {
+    console.error(`서버가 뜨지 않았습니다. 기록: ${log}`)
+    try { console.error(fs.readFileSync(log, 'utf8').split('\n').slice(-10).join('\n')) } catch { /* 없으면 그만 */ }
+    process.exit(1)
+  }
+
+  console.log(`대상 ${TARGET}`)
+
+  for (const page of PAGES) {
+    // 🔴 맨 주소로 연다. 사람이 처음 여는 주소가 이것이고, 파라미터를 붙이면
+    //    부트스트랩의 다른 갈래를 타서 크래시 지점을 우회할 수 있다.
+    const dom = execFileSync(chrome, [
+      '--headless=new', '--disable-gpu', '--no-sandbox',
+      // 자바스크립트가 끝날 시간을 준다. 큰 저장소는 그래프를 만드느라 느리다.
+      '--virtual-time-budget=20000',
+      '--dump-dom', `http://127.0.0.1:${PORT}${page.path}`,
+    ], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true })
+
+    console.log(`\n${page.path}  ${page.what}  ·  DOM ${dom.length.toLocaleString()} bytes`)
+    for (const m of page.must) {
+      const ok = m.re.test(dom)
+      console.log(`  ${ok ? '통과' : '실패'}  ${m.what}`)
+      if (!ok) failed++
+    }
+  }
+
+  if (failed) {
+    console.error('\n화면이 뜨지 않았습니다 — 부트스트랩이 중간에 죽었을 수 있습니다.')
+    console.error('브라우저 콘솔을 보세요. 문법은 멀쩡한데 실행이 죽는 경우가 많습니다')
+    console.error('(선언 순서·TDZ·없는 id 참조).')
+  }
+} finally {
+  try { server.kill() } catch { /* 이미 죽었으면 그만 */ }
+  if (process.platform === 'win32') {
+    try { spawnSync('taskkill', ['/PID', String(server.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }) } catch { /* 그만 */ }
+  }
+  try { fs.closeSync(out) } catch { /* 그만 */ }
+}
+
+if (failed) process.exit(1)
+console.log('\n화면 연기 검사 통과')

package/tools/topicgraph.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+토픽 그래프 측정기 — docs/DECISIONS.md 의 D5·D6·D7·D9·D10 근거를 재현한다.
+
+ROS2 처럼 배선이 문자열로 표현되는 코드베이스에서
+"어떤 파일이 어떤 파일과 이어져 있고, 시작점에서 몇 단계 떨어져 있는가"를 센다.
+
+    python tools/topicgraph.py <소스루트> [시작파일] [--hub-cap N]
+
+    python tools/topicgraph.py ../e101_hj/redesign/.../ros2_ws/src \\
+        bbiyong_base/bbiyong_base/cmd_mux_node.py --hub-cap 6
+
+이것은 제품이 아니라 **측정 도구**다. 정적 문자열만 본다.
+그래서 파라미터를 통한 간접 배선을 놓치며, 실제로 놓쳤다 (DECISIONS.md D5).
+그 한계를 보여주는 것도 이 스크립트의 역할이다.
+"""
+
+import argparse
+import collections
+import os
+import re
+import sys
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+TOPIC = re.compile(r'["\'](/[A-Za-z0-9_/]{2,})["\']')
+
+
+def collect(root):
+    """파일별로 등장하는 토픽 문자열을 모은다."""
+    files = {}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d != "__pycache__"]
+        for name in filenames:
+            if not name.endswith(".py"):
+                continue
+            path = os.path.join(dirpath, name)
+            try:
+                src = open(path, encoding="utf-8", errors="ignore").read()
+            except OSError:
+                continue
+            topics = set(TOPIC.findall(src))
+            if topics:
+                files[os.path.relpath(path, root).replace("\\", "/")] = topics
+    return files
+
+
+def layers_from(topic_files, start, hub_cap=None):
+    """
+    시작 파일에서 너비우선으로 뻗어나가며 깊이별 파일 집합을 만든다.
+
+    hub_cap 을 주면 그보다 많은 파일이 공유하는 토픽은 엣지에서 제외한다.
+    전역 방송 신호(/estop 등)가 무관한 노드들을 서로 1홉 거리로 만드는 것을 막는다.
+    """
+    adj = collections.defaultdict(set)
+    for topic, group in topic_files.items():
+        if hub_cap is not None and len(group) > hub_cap:
+            continue
+        for a in group:
+            adj[a] |= group - {a}
+
+    seen, out, frontier = {start}, [], {start}
+    while frontier:
+        nxt = set()
+        for node in frontier:
+            nxt |= adj[node] - seen
+        if not nxt:
+            break
+        seen |= nxt
+        out.append(nxt)
+        frontier = nxt
+    return out
+
+
+def size_histogram(root):
+    buckets = [("<100", 0), ("100-300", 0), ("300-600", 0), ("600-1000", 0), ("1000+", 0)]
+    counts = dict(buckets)
+    total_lines = 0
+    biggest = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d != "__pycache__"]
+        for name in filenames:
+            if not name.endswith(".py"):
+                continue
+            path = os.path.join(dirpath, name)
+            try:
+                n = sum(1 for _ in open(path, encoding="utf-8", errors="ignore"))
+            except OSError:
+                continue
+            total_lines += n
+            biggest.append((n, os.path.relpath(path, root).replace("\\", "/")))
+            key = ("<100" if n < 100 else "100-300" if n < 300 else
+                   "300-600" if n < 600 else "600-1000" if n < 1000 else "1000+")
+            counts[key] += 1
+    biggest.sort(reverse=True)
+    return counts, total_lines, biggest
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("root")
+    ap.add_argument("start", nargs="?")
+    ap.add_argument("--hub-cap", type=int, default=6)
+    args = ap.parse_args()
+
+    files = collect(args.root)
+    topic_files = collections.defaultdict(set)
+    for f, topics in files.items():
+        for t in topics:
+            topic_files[t].add(f)
+
+    counts, total_lines, biggest = size_histogram(args.root)
+    n_files = sum(counts.values())
+
+    print(f"== 규모 ==")
+    print(f"  {n_files}개 .py, {total_lines:,}줄")
+    print(f"  토픽 문자열을 가진 파일 {len(files)}개, 토픽 {len(topic_files)}개\n")
+
+    print("== 크기 분포 ==")
+    for label in ["<100", "100-300", "300-600", "600-1000", "1000+"]:
+        print(f"  {label:>9}줄  {counts[label]:3}개")
+    tail = sum(n for n, _ in biggest[:5])
+    if total_lines:
+        print(f"  상위 5개 파일이 전체의 {tail / total_lines * 100:.0f}% ({tail:,}줄)")
+    for n, f in biggest[:5]:
+        print(f"      {n:5}줄  {f}")
+    print()
+
+    print(f"== 허브 토픽 (많은 파일이 공유) ==")
+    for t, group in sorted(topic_files.items(), key=lambda kv: -len(kv[1]))[:6]:
+        flag = "  ← 허브" if len(group) > args.hub_cap else ""
+        print(f"  {len(group):3}개 파일  {t}{flag}")
+    print()
+
+    if not args.start:
+        print("시작 파일을 주면 깊이별 확산을 잽니다.")
+        return
+    if args.start not in files:
+        print(f"시작 파일을 찾을 수 없습니다: {args.start}")
+        return
+
+    for cap, label in [(None, "허브 제한 없음"), (args.hub_cap, f"{args.hub_cap}개 초과 토픽 제외")]:
+        print(f"== {args.start} 로부터의 깊이 ({label}) ==")
+        total = 1
+        for depth, group in enumerate(layers_from(topic_files, args.start, cap), 1):
+            total += len(group)
+            mark = "  ← 요약 한계" if depth == 3 else ""
+            print(f"  깊이 {depth}: +{len(group):3}개  (누적 {total:3}){mark}")
+        print()
+
+
+if __name__ == "__main__":
+    main()