deel-local-cli 1.20.12 → 2.0.0

package/src/tools/kiwi.js

@@ -35,6 +35,21 @@
  * 40억이면 그대로 40억 칸을 잡으려 든다. 그래서 개수를 볼 때마다 남은
  * 바이트와 견준다 — 어떤 값이든 최소 한 바이트는 먹으므로, 남은 바이트보다
  * 많은 개수는 그 자리에서 거짓이다.
+ *
+ * ── 깨진 바이트를 만나면 (8회차 · 바깥) ────────────────────────────────
+ *
+ * 규약은 하나다 — **어디까지 읽었는지 말하고 멈춘다.**
+ *
+ * 한 파일 안에 이것과 반대인 두 버릇이 같이 있었다. 스키마 갈래 바이트가
+ * 0·1·2 가 아니면 조용히 ENUM 으로 **바꿔서** 계속 읽었고(그 뒤는 전부 다른
+ * 값이 되는데 아무 말도 안 나온다), 알맹이에서 모르는 칸 번호를 만나면
+ * **이미 읽은 것까지** 말없이 버리고 던졌다. 지어내는 쪽과 버리는 쪽이
+ * 한 파일에 같이 있으면 읽는 쪽은 무엇을 받았는지 알 길이 없다.
+ *
+ * 그래서 아래 여기까지() 하나로 묶는다. 멈추는 것은 같고, 오류에 **바이트
+ * 자리**와 **여태 읽은 것**을 달아 보낸다. 그걸 쓸지는 부르는 쪽이 정한다 —
+ * fig.js 는 안 쓴다(「반만 맞는 시안은 틀린 시안보다 나쁘다」). 버리는 것과
+ * 버릴지를 고르게 하는 것은 다르다.
  */
 
 const 기본형 = ['bool', 'byte', 'int', 'uint', 'float', 'string', 'int64', 'uint64'];
@@ -49,6 +64,17 @@ const 깊이최대 = 100;
 /** 실수 네 바이트를 뒤집어 볼 때 쓰는 창. 새로 만들지 않고 하나를 돌려 쓴다. */
 const 실수판 = new DataView(new ArrayBuffer(4));
 
+/**
+ * 깨진 바이트를 만났다 — **어디까지 읽었는지 말하고 멈춘다.**
+ *
+ * @param {string} 말      무엇이 깨졌나
+ * @param {number} 자리    그때까지 읽은 바이트 수
+ * @param {*} [읽은것]     여태 읽어 놓은 것. 말없이 버리지 않는다.
+ */
+function 여기까지(말, 자리, 읽은것 = null) {
+  return Object.assign(new Error(`${말} — 바이트 ${자리} 까지 읽었습니다`), { 자리, 읽은것 });
+}
+
 /**
  * 바이트를 앞에서부터 읽는 자.
  *
@@ -159,14 +185,27 @@ export class 읽개 {
  */
 export function 스키마읽기(buf) {
   const r = new 읽개(buf);
-  const 개수 = r.varuint();
+  // 개수는 스키마 쪽에서도 **남은 바이트와 대조하고** 들어간다. 여기만 날 varuint 라,
+  // 「정의 40억 개」 라고 적힌 조각이 그 대조 없이 루프에 들어가 엉뚱한 말로 터졌다
+  // (`문자열이 끝나지 않았습니다`). 정의 하나도 칸 하나도 최소 한 바이트는 먹는다.
+  const 개수 = r.개수();
   if (개수 > 정의최대) throw new Error(`정의가 ${개수}개 — Kiwi 스키마가 아닌 것 같습니다`);
 
   const 정의들 = [];
   for (let i = 0; i < 개수; i += 1) {
     const 이름 = r.문자열();
-    const 갈래 = 갈래이름[r.바이트()] ?? 'ENUM';
-    const 칸수 = r.varuint();
+    /*
+     * 모르는 갈래 바이트를 ENUM 으로 **바꾸지 않는다.**
+     *
+     * 갈래는 0=ENUM · 1=STRUCT · 2=MESSAGE 셋뿐이고, 셋이 서로 다르게 읽힌다.
+     * 모르는 값을 ENUM 으로 치면 그 정의부터 뒤가 전부 다른 값으로 읽히는데
+     * 오류는 안 난다 — 갈래 바이트 7 하나가 `{"갈래":"ENUM","칸들":[]}` 로
+     * 조용히 둔갑했다. 지어내느니 여기까지 읽었다고 말하고 멈춘다.
+     */
+    const 갈래바이트 = r.바이트();
+    const 갈래 = 갈래이름[갈래바이트];
+    if (!갈래) throw 여기까지(`${이름} 의 정의 갈래가 ${갈래바이트} — 0·1·2 만 있습니다`, r.i, 정의들);
+    const 칸수 = r.개수();
     if (칸수 > 칸최대) throw new Error(`${이름} 의 칸이 ${칸수}개 — 스키마가 깨졌습니다`);
     const 칸들 = [];
     for (let j = 0; j < 칸수; j += 1) {
@@ -256,8 +295,10 @@ function 정의읽기(스키마, r, 번호, 깊이, 담나, 남길까) {
        * 여기서는 수천만 번이다. 값을 안 쓸 때만 쓰는 길이라, 담는 쪽 결과는
        * 한 글자도 안 달라진다.
        */
+      // 개수 대조는 바로 위 `r.개수()` 가 이미 했다. 여기 한 번 더 있던 같은 대조는
+      // **어떤 입력에도 안 걸리는** 죽은 단언이었다 — 지킨다고 적혀 있을 뿐 아무것도
+      // 안 지키는 줄은, 다음 사람이 그 줄을 믿고 위쪽 대조를 빼게 만든다.
       if (!이칸담나 && f.형 === -2) {
-        if (n > r.남은) throw new Error(`바이트 배열이 남은 것보다 깁니다 (${n} > ${r.남은})`);
         r.i += n;
         return;
       }
@@ -281,12 +322,16 @@ function 정의읽기(스키마, r, 번호, 깊이, 담나, 남길까) {
   // MESSAGE — 번호 0 이 끝이다. 스키마에 없는 번호를 만나면 **거기서 멈춘다.**
   // 길이가 안 적혀 있어서 건너뛸 수가 없다. 짐작으로 계속 읽으면 그 뒤가
   // 전부 헛것이 되므로, 아는 데까지만 읽었다고 말하는 편이 낫다.
+  //
+  // 그 「말한다」 가 없었다. 그냥 던져서 **이미 읽은 것까지** 같이 사라졌고,
+  // 부르는 쪽은 한 글자도 못 읽은 것과 구별할 수 없었다. 오류에 바이트 자리와
+  // 여기까지 읽은 것을 달아 보낸다 — 쓸지는 부르는 쪽이 정한다.
   const 칸표 = new Map(d.칸들.map((f) => [f.값, f]));
   for (;;) {
     const id = r.varuint();
     if (id === 0) break;
     const f = 칸표.get(id);
-    if (!f) throw new Error(`${d.이름} 에 모르는 칸 번호 ${id} — 여기서 더 못 읽습니다`);
+    if (!f) throw 여기까지(`${d.이름} 에 모르는 칸 번호 ${id} — 여기서 더 못 읽습니다`, r.i, 것);
     한칸(f);
   }
   return 것;

package/src/tools/lsp.js

@@ -29,18 +29,35 @@ import { 갈래, 프로젝트갈래 } from '../lsp/servers.js';
 import { 찾을개수 } from '../agent/budget.js';
 import { 말, 세말 } from '../i18n/index.js';
 
-/** 한 자리를 사람이 읽을 한 줄로. 그 줄의 글까지 붙여야 열어 보지 않고도 안다. */
-function 한줄(scope, uri, 범위) {
+/**
+ * 한 자리를 사람이 읽을 한 줄로. 그 줄의 글까지 붙여야 열어 보지 않고도 안다.
+ *
+ * ── 파일은 파일마다 **한 번** (사냥4 W3) ─────────────────────────────────
+ *
+ * 여기가 **자리 하나마다** 그 파일을 통째로 다시 읽었다. 4만 줄짜리 파일에 참조가
+ * 5000곳이면 5000번을 읽는다. 게다가 `trim()` 으로 뗀 줄은 V8 에서 원래 글의 **조각**
+ * 이라, 그 한 줄이 파일 전체를 붙들고 놓지 않았다 — 5000줄이 5000벌을 붙들어 힙이 넘쳤다.
+ *
+ * 그래서 한 번 부를 동안 같은 파일은 줄표 에서 꺼내 쓰고, 뗀 글은 **새 글로 옮겨 적는다**
+ * (Buffer 를 거치면 조각이 아니라 제 몸을 가진 글이 된다). 부르는 쪽(Refs)은 창에 안 실을
+ * 자리는 아예 여기로 안 보낸다.
+ *
+ * @param 줄표 한 번 부를 동안 같이 쓰는 표 (파일 → 줄들 | null). 안 주면 그 자리에서 읽는다.
+ */
+function 한줄(scope, uri, 범위, 줄표 = new Map()) {
   let abs;
   try { abs = fileURLToPath(uri); } catch { abs = String(uri); }
   const 줄번호 = (범위?.start?.line ?? 0) + 1;
-  let 글 = '';
-  try {
-    const 줄들 = readFileSync(abs, 'utf8').split(/\r?\n/);
-    글 = (줄들[줄번호 - 1] ?? '').trim();
-  } catch { /* 못 읽으면 자리만 준다 */ }
+  // 윈도우는 서버가 드라이브 글자를 소문자로 적어 온다(c%3A) — 같은 파일을 두 번 읽지 않게.
+  const 열쇠 = process.platform === 'win32' ? abs.toLowerCase() : abs;
+  if (!줄표.has(열쇠)) {
+    try { 줄표.set(열쇠, readFileSync(abs, 'utf8').split(/\r?\n/)); } catch { 줄표.set(열쇠, null); /* 못 읽으면 자리만 준다 */ }
+  }
+  let 글 = (줄표.get(열쇠)?.[줄번호 - 1] ?? '').trim();
+  if (글.length > 160) 글 = 글.slice(0, 160) + '…';
+  글 = Buffer.from(글, 'utf8').toString('utf8');
   const 보일 = scope?.show ? (() => { try { return scope.show(abs); } catch { return abs; } })() : abs;
-  return { 파일: 보일, 줄: 줄번호, 글: 글.length > 160 ? 글.slice(0, 160) + '…' : 글, abs };
+  return { 파일: 보일, 줄: 줄번호, 글, abs };
 }
 
 /** LSP 의 답은 하나일 수도, 목록일 수도, LocationLink 일 수도 있다. 다 같은 모양으로 편다. */
@@ -121,9 +138,16 @@ async function 자리잡기(서버, scope, { 이름, 파일, 줄 }) {
   }
   if (답.오류) return { 오류: 답.오류 };
   const 것들 = (Array.isArray(답.값) ? 답.값 : []).filter((s) => s?.name);
-  // 이름이 똑같은 것만. 서버는 대개 부분 일치까지 준다.
+  /*
+   * 이름이 똑같은 것만. 서버는 대개 부분 일치까지 준다.
+   *
+   * 똑같은 것이 없을 때 **아무 부분 일치나** 받았다 — `셈` 을 물으면 `셈하기` 를 짚고 답은
+   * 「셈 — 정의 1곳」 이었다 (2.0.0 6회차 LS1). 남의 정의를 내 것처럼 준 것이다. 되받는 것은
+   * 이름이 **낱말로 들어 있는** 것뿐이다 — 서버에 따라 `Cls.foo` · `foo(int)` 처럼 이름을 꾸며
+   * 주기 때문이다. 되받았으면 무엇을 짚었는지 같이 돌려준다 (닮은이름).
+   */
   const 딱맞는 = 것들.filter((s) => s.name === 이름);
-  const 쓸것 = 딱맞는.length ? 딱맞는 : 것들;
+  const 쓸것 = 딱맞는.length ? 딱맞는 : 것들.filter((s) => 칸찾기(String(s.name), 이름) >= 0);
   if (!쓸것.length) {
     return {
       오류: `${이름} 을(를) 못 찾았습니다`
@@ -163,7 +187,25 @@ async function 자리잡기(서버, scope, { 이름, 파일, 줄 }) {
     서버.보여주기(abs);
   } catch { /* 그대로 간다 */ }
 
-  return { 자리: { uri: 첫.uri, position }, 후보 };
+  return { 자리: { uri: 첫.uri, position }, 후보, 닮은이름: 딱맞는.length ? null : 첫.이름 };
+}
+
+/**
+ * 모델이 준 줄 번호. **따옴표가 붙어 와도 숫자로 본다.**
+ *
+ * 스키마에 number 라고 적어 두어도 `"line": "42"` 로 보내는 모델이 있다.
+ * `Number.isFinite('42')` 는 false 라 그 줄이 통째로 버려졌고, 자리잡기 는
+ * 줄을 안 준 것으로 보고 **파일 처음부터** 이름을 찾았다 — 문자열 42 는 4번
+ * 줄을, 숫자 42 는 41번 줄을 짚었다. 엉뚱한 줄을 짚어 놓고 찾았다고 답하므로
+ * 잘못됐다는 신호가 어디에도 안 남는다.
+ *
+ * 빈 값·빈 글자는 「안 준 것」 이다. Number('') 가 0 이라 그냥 넘기면 0번 줄을
+ * 짚으려 든다.
+ */
+function 줄값(값) {
+  if (값 === null || 값 === undefined) return null;
+  const n = typeof 값 === 'string' ? (값.trim() === '' ? NaN : Number(값)) : 값;
+  return typeof n === 'number' && Number.isFinite(n) ? n : null;
 }
 
 /** 두 도구가 같은 앞머리를 쓴다 — 서버 얻고 자리 잡는 데까지. */
@@ -187,19 +229,44 @@ async function 채비(args, ctx) {
   if (!서버) return { 오류: '언어 서버가 이 자리에 없습니다. Grep · Outline 을 쓰세요.' };
 
   const 잡음 = await 자리잡기(서버, ctx.scope, {
-    이름, 파일, 줄: Number.isFinite(args.line) ? Number(args.line) : null,
+    이름, 파일, 줄: 줄값(args.line),
   });
   if (잡음.오류) return { 오류: 잡음.오류 };
-  return { 이름, 서버, 자리: 잡음.자리, 후보: 잡음.후보 ?? [] };
+  return { 이름, 서버, 자리: 잡음.자리, 후보: 잡음.후보 ?? [], 닮은이름: 잡음.닮은이름 ?? null };
 }
 
-/** 여러 곳에 같은 이름이 있으면 그대로 알려 준다. 하나를 골라 주고 아닌 척하지 않는다. */
+/**
+ * 여러 곳에 같은 이름이 있으면 그대로 알려 준다. 하나를 골라 주고 아닌 척하지 않는다.
+ *
+ * 가르는 열쇠는 **파일과 컨테이너**다. 파일만 봤더니 한 파일 안의 서로 다른 둘(`server.go` 의
+ * `Server.Run` · `Worker.Run`)을 하나로 쳐서 말이 없었다 (2.0.0 6회차 LS2). 보기가 두 **파일**
+ * (`A.go` · `B.go`)로 적혀 있었는데, 그건 파일만 봐도 갈리는 판이라 설명하는 고장과 어긋났다.
+ * 그렇다고 줄마다 세면, 겹쳐쓰기(overload)처럼 같은
+ * 것이 여러 줄로 오는 흔한 자리에서 거짓 경고가 난다 — 컨테이너까지 같으면 같은 것으로 친다.
+ */
 function 여럿이면(후보, scope) {
   if (!Array.isArray(후보) || 후보.length < 2) return null;
-  const 파일들 = new Set(후보.map((c) => { try { return scope.show(fileURLToPath(c.uri)); } catch { return c.uri; } }));
-  if (파일들.size < 2) return null;
-  return `같은 이름이 ${파일들.size}곳에 있습니다: ${[...파일들].slice(0, 5).join(' · ')}`
-    + `${파일들.size > 5 ? ' …' : ''}. 다른 것을 뜻했다면 file_path 로 짚어 주세요.`;
+  const 곳들 = new Map();   // [파일, 컨테이너] → 보일 이름
+  const 파일들 = new Set();
+  for (const c of 후보) {
+    let 파일;
+    try { 파일 = scope.show(fileURLToPath(c.uri)); } catch { 파일 = c.uri; }
+    파일들.add(파일);
+    const 컨테이너 = String(c.컨테이너 ?? '');
+    곳들.set(JSON.stringify([파일, 컨테이너]), 컨테이너 ? `${파일} (${컨테이너})` : 파일);
+  }
+  if (곳들.size < 2) return null;
+  const 보일것 = [...곳들.values()];
+  // 한 파일 안에서 갈리면 file_path 로는 못 좁힌다 — 줄까지 짚어야 한다.
+  const 짚는법 = 파일들.size < 2 ? 'file_path 와 line 으로' : 'file_path 로';
+  return `같은 이름이 ${보일것.length}곳에 있습니다: ${보일것.slice(0, 5).join(' · ')}`
+    + `${보일것.length > 5 ? ' …' : ''}. 다른 것을 뜻했다면 ${짚는법} 짚어 주세요.`;
+}
+
+/** 이름이 똑같은 것이 없어 낱말로 든 다른 이름(`Cls.foo` 같은)을 짚었으면 그 이름을 말한다 (자리잡기 의 닮은이름, LS1). */
+function 닮은말(이름, 닮은이름) {
+  if (!닮은이름 || 닮은이름 === 이름) return null;
+  return `「${이름}」 — 이름이 똑같은 것은 없어 「${닮은이름}」 자리를 짚었습니다. 다른 것을 뜻했다면 Grep 으로 보세요.`;
 }
 
 export const DEF_TOOL = {
@@ -233,23 +300,50 @@ export const DEF_TOOL = {
     });
     if (답.오류) return { error: `언어 서버: ${답.오류}` };
 
-    let 곳들 = 자리들펴기(답.값).map((x) => 한줄(ctx.scope, x.uri, x.range));
+    const 줄표 = new Map();   // 같은 파일은 한 번만 읽는다 (한줄 머리말)
+    let 곳들 = 자리들펴기(답.값).map((x) => 한줄(ctx.scope, x.uri, x.range, 줄표));
     // 서버가 정의를 못 주면(선언만 있는 자리 등) 심볼 검색으로 잡은 자리를 준다.
     // 빈손으로 돌려보내는 것보다 낫고, 어디서 온 값인지 같이 말해 준다.
     let 어디서 = 'definition';
     if (!곳들.length && 후보.length) {
-      곳들 = 후보.map((c) => 한줄(ctx.scope, c.uri, c.range));
+      곳들 = 후보.map((c) => 한줄(ctx.scope, c.uri, c.range, 줄표));
       어디서 = 'workspace/symbol';
     }
     if (!곳들.length) return { summary: `${이름}: ${말('lsp.noDef')}`, found: 0 };
 
+    /*
+     * ── 「골라 준 것이 아니다」 는 말은 **모델에게** 가야 한다 ────────────
+     *
+     * 이 말을 summary 에만 붙여 놨었다. 그런데 모델이 받는 글은 content 다 —
+     * loop.js 의 실을글() 은 content 가 비지 않으면 그것만 싣고, 비었을 때만
+     * summary 로 내려간다. 즉 **줄 자리가 있을 때는 이 말이 절대 안 갔다.**
+     *
+     * 사람 화면에는 「같은 이름이 2곳에 있습니다」 가 멀쩡히 찍히니 아무도
+     * 눈치를 못 챈다. 정작 모델은 자리 하나만 받고 그게 유일한 정의인 줄
+     * 알고, 남의 파일에 있는 같은 이름을 고쳐 놓고 답을 맺는다. 이 도구가
+     * 하나를 골라 주고 아닌 척하지 않겠다고 한 약속이 그 자리에서 깨진다.
+     *
+     * 두 곳에 다 적는다. 사람이 본 말과 모델이 받은 말이 같아야 한다.
+     */
     const 여럿 = 여럿이면(후보, ctx.scope);
+    /*
+     * 이름이 똑같은 것이 없어 꾸민 이름을 짚었거나(LS1), 정의를 못 받아 심볼 검색 자리를
+     * 줬으면(LS3) 그렇다고 **모델이 받는 글에도** 적는다 — 바로 위와 같은 까닭이다.
+     * 출처를 `source` 칸에만 두었더니 사람에게도 모델에게도 안 갔다 (2.0.0 6회차).
+     */
+    const 덧말 = [
+      닮은말(이름, 준비.닮은이름),
+      어디서 === 'workspace/symbol'
+        ? '언어 서버가 정의를 못 줘서 심볼 검색으로 찾은 자리입니다 — 정의가 아니라 선언일 수 있습니다.' : null,
+      여럿,
+    ].filter(Boolean);
+    const 글 = 곳들.map((l) => `${l.파일}:${l.줄}  ${l.글}`).join('\n');
     return {
-      summary: `${이름} — ${말('lsp.defs', { n: 세말('places', 곳들.length) })}${여럿 ? `\n${여럿}` : ''}`,
+      summary: `${이름} — ${말('lsp.defs', { n: 세말('places', 곳들.length) })}${덧말.length ? `\n${덧말.join('\n')}` : ''}`,
       found: 곳들.length,
       source: 어디서,
       locations: 곳들,
-      content: 곳들.map((l) => `${l.파일}:${l.줄}  ${l.글}`).join('\n'),
+      content: 덧말.length ? `${글}\n\n${덧말.join('\n')}` : 글,
     };
   },
 };
@@ -286,12 +380,22 @@ export const REFS_TOOL = {
     });
     if (답.오류) return { error: `언어 서버: ${답.오류}` };
 
-    const 곳들 = 자리들펴기(답.값).map((x) => 한줄(ctx.scope, x.uri, x.range));
+    // 여기서는 자리만 편다. 줄 글은 창에 실을 것만 아래에서 읽는다 (한줄 머리말, 사냥4 W3).
+    const 곳들 = 자리들펴기(답.값);
+    const 여럿 = 여럿이면(후보, ctx.scope);
+    const 닮은 = 닮은말(이름, 준비.닮은이름);
     if (!곳들.length) {
+      /*
+       * 「안 쓴다」 는 **짚은 하나**에 대한 답이다. 같은 이름이 다른 곳에도 있으면 그 말을 같이
+       * 해야 한다 — 빼면 모델은 지워도 되는 줄 알고 멀쩡히 쓰이는 쪽을 지운다 (2.0.0 6회차 LS5).
+       */
       return {
-        summary: `${이름}: ${말('lsp.noRefs')}`
-          + ' 정말 안 쓰는 것일 수도 있고, 언어 서버가 아직 색인 중일 수도 있습니다 —'
-          + ' 지우기 전에 Grep 으로 한 번 더 보세요.',
+        summary: [
+          `${이름}: ${말('lsp.noRefs')}`
+            + ' 정말 안 쓰는 것일 수도 있고, 언어 서버가 아직 색인 중일 수도 있습니다 —'
+            + ' 지우기 전에 Grep 으로 한 번 더 보세요.',
+          닮은, 여럿,
+        ].filter(Boolean).join('\n'),
         found: 0,
       };
     }
@@ -299,7 +403,9 @@ export const REFS_TOOL = {
     // 창에 맞춰 자른다. 자른 것은 자랐다고 말한다 — 조용히 자르면 모델은
     // 그게 전부인 줄 알고 나머지 자리를 안 고친다.
     const 한도 = 찾을개수(ctx.모델컨텍스트 ?? null);
-    const 보일것 = 곳들.slice(0, 한도);
+    // 자르고 **나서** 읽는다. 창에 안 실을 70곳의 파일까지 열 까닭이 없다.
+    const 줄표 = new Map();
+    const 보일것 = 곳들.slice(0, 한도).map((x) => 한줄(ctx.scope, x.uri, x.range, 줄표));
     const 남은 = 곳들.length - 보일것.length;
 
     // 파일별로 묶어야 읽힌다. 같은 파일 열 줄이 흩어져 있으면 몇 파일을
@@ -313,16 +419,42 @@ export const REFS_TOOL = {
       .map(([f, 줄들]) => `${f} (${줄들.length})\n` + 줄들.map((l) => `  ${l.줄}: ${l.글}`).join('\n'))
       .join('\n');
 
-    const 여럿 = 여럿이면(후보, ctx.scope);
+    /*
+     * ── 「70곳은 안 실었습니다」 가 모델에게는 안 갔다 ────────────────────
+     *
+     * 바로 위에서 "자른 것은 자랐다고 말한다" 고 해 놓고, 그 말을 summary
+     * 에만 붙였다. 모델이 받는 글은 content 이고(loop.js 의 실을글), content
+     * 가 비지 않으면 summary 는 아예 안 실린다. 그러니 **자를 것이 있을 때는
+     * 반드시** 이 말이 빠졌다 — 잘랐다는 것을 알려야 할 바로 그때만.
+     *
+     * 8k 모델이면 한도가 50이다(budget.js 의 찾을개수는 작은 모델에서 50에서
+     * 바닥을 친다). 참조 120곳 중 50곳을 받은 모델은 그 50곳을 고치고
+     * 「모든 참조를 고쳤습니다」 로 답을 맺는다. 남은 70곳은 돌려 본 뒤에야
+     * 드러나고, 그때는 이미 다른 것도 같이 고쳐 놓은 뒤다.
+     *
+     * 사람 화면(summary)에는 그대로 두고, 글 끝에도 같이 적는다. 같은 말을
+     * 두 번 적는 것이 아니라, 여태 **한쪽에만** 적혀 있던 것을 마저 적는 것이다.
+     */
+    const 잘림말 = 남은 ? `(${남은}곳은 자리가 모자라 안 실었습니다)` : '';
+    /*
+     * 파일 수는 **자르기 전 전체**로 센다. 보인 50곳(묶음)으로 셌더니 두 파일에 걸친 120곳이
+     * 「120곳 · 1개 파일」 이 됐다 (2.0.0 6회차 LS4) — 몇 파일을 고쳐야 하는지 먼저 말하는
+     * 줄이 틀린 수를 준다. 줄 글은 안 읽고 주소만 본다.
+     */
+    const 파일수 = new Set(곳들.map((x) => {
+      try { return ctx.scope.show(fileURLToPath(x.uri)); } catch { return x.uri; }
+    })).size;
+    const 덧말 = [잘림말, 닮은, 여럿].filter(Boolean);
     return {
-      summary: `${이름} — ${말('lsp.refs', { 자리: 세말('places', 곳들.length), 파일: 세말('files', 묶음.size) })}`
-        + (남은 ? ` (${남은}곳은 자리가 모자라 안 실었습니다)` : '')
+      summary: `${이름} — ${말('lsp.refs', { 자리: 세말('places', 곳들.length), 파일: 세말('files', 파일수) })}`
+        + (잘림말 ? ` ${잘림말}` : '')
+        + (닮은 ? `\n${닮은}` : '')
         + (여럿 ? `\n${여럿}` : ''),
       found: 곳들.length,
-      files: 묶음.size,
+      files: 파일수,
       truncated: 남은 > 0,
       locations: 보일것,
-      content: 글,
+      content: 덧말.length ? `${글}\n\n${덧말.join('\n')}` : 글,
     };
   },
 };

package/src/tools/outline.js

@@ -54,16 +54,40 @@ const 규칙 = {
     [/^\s*(?:export\s+)?(?:const|let|var)\s+([\p{L}$_][\p{L}\p{N}$_]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[\p{L}$_][\p{L}\p{N}$_]*)\s*=>/u, 'fn'],
     [/^\s*(?:export\s+)?(?:interface|type|enum)\s+([\p{L}$_][\p{L}\p{N}$_]*)/u, 'type'],
     [/^\s*export\s+(?:const|let|var)\s+([\p{L}$_][\p{L}\p{N}$_]*)/u, 'const'],
-    // 클래스 안의 메서드. 들여쓰기가 있고 괄호로 이어지는 이름.
-    [/^\s{2,}(?:static\s+|async\s+|get\s+|set\s+|#)?([\p{L}$_][\p{L}\p{N}$_]*)\s*\([^)]*\)\s*\{/u, 'method'],
+    /*
+     * 클래스 안의 메서드. 들여쓰기가 있고 괄호로 이어지는 이름.
+     *
+     * 수식어는 **여러 개 붙는다.** 여기가 `(?:static\s+|async\s+|…)?` 라 하나까지만
+     * 먹었고, 그래서 `static async 불러오기()` 는 `static ` 을 먹은 뒤 `async` 를
+     * 이름으로 잡으려다 뒤의 `(` 를 못 만나 **아예 안 걸렸다.** 요즘 코드에서 제일
+     * 흔한 조합이 통째로 뼈대에서 빠지고, 모델은 그 메서드가 없는 줄 안다.
+     * 제너레이터의 `*` 와 사사로운 이름의 `#` 도 여기서 같이 받는다.
+     */
+    /*
+     * 들여쓰기를 `\s{2,}` 로 잡던 때, **탭으로 들여쓴 파일은 한 개도 안 걸렸다.**
+     * 탭 들여쓰기는 한 단이 탭 하나라서다. `.editorconfig` 가 `indent_style = tab`
+     * 인 저장소에서는 위 고침이 무엇이든 클래스 메서드가 통째로 빠지고, 클래스
+     * 이름만 달랑 뜬다 — 모델은 그 클래스에 메서드가 없는 줄 안다. 탭 하나 또는
+     * 빈칸 둘로 본다. 들여쓰기가 아예 없는 `이름() {` 은 부름이라 그대로 막힌다.
+     */
+    [/^(?:\t| {2,})\s*(?:(?:static|async|get|set)\s+)*\*?\s*#?([\p{L}$_][\p{L}\p{N}$_]*)\s*\([^)]*\)\s*\{/u, 'method'],
   ],
   py: [
     [/^\s*class\s+([\p{L}_][\p{L}\p{N}_]*)/u, 'class'],
     [/^\s*(?:async\s+)?def\s+([\p{L}_][\p{L}\p{N}_]*)/u, 'fn'],
     [/^([A-Z_][A-Z0-9_]{2,})\s*[:=]/, 'const'],
   ],
+  /*
+   * java 표는 `.kt`·`.kts`·`.scala`·`.groovy` 도 같이 쓴다 — 그리고 설명서(OUTLINE_TOOL)가
+   * 「java/kotlin 을 읽는다」 고 적어 둔다. 그런데 여기 자바 두 줄뿐이던 때,
+   * Kotlin 의 `fun` 과 Scala·Groovy 의 `def` 는 **어느 무늬에도 안 걸렸다.**
+   * `.kt` 파일이 클래스 이름 하나만 달고 떴고, 모델은 그 클래스에 함수가 없는 줄
+   * 안다 — 이 파일 머리말이 「모르는 것은 모른다고 말한다」 고 적어 둔 것과 반대로,
+   * 읽는다고 해 놓고 반만 읽었다. `data class`·`object`·맨 위 `fun` 까지 같이 본다.
+   */
   java: [
-    [/^\s*(?:public|private|protected)?\s*(?:static\s+)?(?:final\s+)?(?:abstract\s+)?(?:class|interface|enum|record)\s+([\p{L}_][\p{L}\p{N}_]*)/u, 'class'],
+    [/^\s*(?:(?:public|private|protected|internal|open|sealed|data|inner|value|annotation|abstract|final|static|case|implicit)\s+)*(?:class|interface|enum|record|object|trait)\s+([\p{L}_][\p{L}\p{N}_]*)/u, 'class'],
+    [/^\s*(?:(?:public|private|protected|internal|open|override|suspend|inline|operator|infix|tailrec|abstract|final|static|implicit)\s+)*(?:fun|def)\s+([\p{L}_][\p{L}\p{N}_]*)/u, 'fn'],
     [/^\s*(?:public|private|protected)\s+(?:static\s+)?(?:final\s+)?[\p{L}\p{N}_<>[\],\s]+\s+([\p{L}_][\p{L}\p{N}_]*)\s*\(/u, 'method'],
   ],
   go: [
@@ -165,8 +189,22 @@ export function 뼈대뽑기(글, 확장) {
 
   const 표 = 규칙[규칙이름] ?? [];
   const 항목 = [];
-  const 본것 = new Set();
-
+  /*
+   * ── 같은 이름을 **지우지 않는다** ────────────────────────────────────
+   *
+   * 여기에 `본것` 이라는 집합이 있었다. 주석은 「같은 이름이 여러 번 걸리는
+   * 규칙이 있다」 — 한 줄이 규칙 여럿에 걸리는 것을 막겠다는 말이었다.
+   * 그건 아래 `break` 가 이미 한다(한 줄은 한 가지로만 센다). 그 집합이 실제로
+   * 한 일은 **파일 전체에서 둘째부터 조용히 지우기**였다:
+   *
+   *     class 앞 { 읽기() {} }   → 남는다
+   *     class 뒤 { 읽기() {} }   → **사라진다**
+   *     ## 보기 … ## 보기        → 뒤엣것이 사라진다
+   *
+   * 뼈대는 「무엇이 **어디에** 있나」 를 보려고 보는 것이다. 이름이 겹친다고
+   * 자리를 지우면, 모델은 그 클래스에 그 메서드가 없는 줄 알고 새로 만들어
+   * 넣는다 — 이 파일 머리말이 없애려던 바로 그 일이다.
+   */
   for (const [i, 한줄] of 줄들.entries()) {
     // 주석 줄은 건너뛴다. 주석 안의 예제 코드가 뼈대로 올라오면 안 된다.
     if (/^\s*(?:\/\/|\/\*|\*|#(?!\s*[#!])|--)/.test(한줄) && 규칙이름 !== 'md') continue;
@@ -178,16 +216,18 @@ export function 뼈대뽑기(글, 확장) {
       let 실갈래 = 갈래;
       if (갈래 === '#' && m[2] !== undefined) {
         const 깊이 = 규칙이름 === 'md' ? m[1].length : Number(m[1]);
-        이름 = `${'  '.repeat(Math.max(0, 깊이 - 1))}${m[2]}`;
+        // `짧게` 는 빈칸을 접고 trim 한다. 들여쓰기를 먼저 붙이면 거기서 지워져 한 번도 안 나갔다 —
+        // 글을 먼저 줄이고 들여쓰기는 뒤에 붙인다 (6회차 뼈대6bc-b OL3).
+        const 글 = 짧게(m[2]);
+        이름 = 글 && `${'  '.repeat(Math.max(0, 깊이 - 1))}${글}`;
         실갈래 = `h${깊이}`;
       } else {
-        이름 = m[1];
+        이름 = 짧게(m[1]);
+        // if·for 거르기는 메서드 규칙이 `if (…) {` 를 잡는 것을 막는 자리다. 헤딩에는 안 건다 —
+        // 걸면 `## class` · `## new` 같은 문서 제목이 뼈대에서 사라졌다 (6회차 뼈대6bc-b OL4).
+        if (이름아님.has(이름)) continue;
       }
-      이름 = 짧게(이름);
-      if (!이름 || 이름아님.has(이름.trim())) continue;
-      const 열쇠 = `${실갈래}|${이름.trim()}`;
-      if (본것.has(열쇠)) continue;       // 같은 이름이 여러 번 걸리는 규칙이 있다
-      본것.add(열쇠);
+      if (!이름) continue;
       항목.push({ 줄: i + 1, 갈래: 실갈래, 이름 });
       break;                              // 한 줄은 한 가지로만 센다
     }