aura-basetools 0.7.0 → 0.13.1

package/locator-lab/locator-api.mjs

@@ -23,24 +23,28 @@ import { indexFile, locateWith, normSpace } from './anchor-core.mjs'
 /**
  * 定位一份源码里的改动点。
  *
- * 四层寻址，按"模型要提供什么"从强到弱排列。每层覆盖上一层够不到的场景，
+ * 五层寻址，按"模型要提供什么"从强到弱排列。每层覆盖上一层够不到的场景，
  * 但**都不要求模型复现字节**——这是它们与 `edit` 的根本差别：
  *
- *   1. `target`  —— 符号名。不读文本，对内容记错免疫。适合改整个函数/类/类型。
- *   2. `lines`   —— 行号区间。模型刚用 `read` 看过文件，输出就是 `<行号>: <文本>`，
+ *   1. `intent`  —— 一段模糊意图（符号名片段 / 短语 / 近似原文）。引擎按固定次序收敛：
+ *                    精确符号 → 符号子串 → 文本锚点；收敛不了就报歧义并给候选，绝不猜。
+ *   2. `target`  —— 符号名。不读文本，对内容记错免疫。适合改整个函数/类/类型。
+ *   3. `lines`   —— 行号区间。模型刚用 `read` 看过文件，输出就是 `<行号>: <文本>`，
  *                    `grep` 也给行号——**位置是它本来就知道的信息**，我却一直只让它给内容。
  *                    把行号纳入地址空间后，符号体内的任意一行都变得可精确寻址。
- *   3. `lineCue` —— 一个词。当模型记不住行号时，说"就在有 resolvePolicy 的那一行"。
+ *   4. `lineCue` —— 一个词。当模型记不住行号时，说"就在有 resolvePolicy 的那一行"。
  *                    只接受**全文件唯一**的线索；不唯一则报歧义并给出候选行号，绝不猜。
- *   4. `anchor`  —— 记得的原文。五级降级匹配，容错性最好但要求模型复现内容。
+ *   5. `anchor`  —— 记得的原文。五级降级匹配，容错性最好但要求模型复现内容。
  *
- * 前两层是**精确**的（要么命中要么报错），后两层是**容错**的。
- * 调用方可以传 `assert` 做内容校验，四层都适用——那才是防止"指到错的行"的那道闸。
+ * `intent` 与其余四层**互斥**（由 `planHunks` 判）：同时给两个地址时谁说了算没有正确答案。
+ * 前两层偏**精确**（要么命中要么报错），后三层偏**容错**。
+ * 调用方可以传 `assert` 做内容校验，五层都适用——那才是防止"指到错的行"的那道闸。
  * 判据是**包含且唯一**：这段文字必须在整个文件里只出现一处，且该处落在受寻址区间内
  * （短引文例外，仍要求与区间整段相等；推导见 {@link ASSERT_RELAX_MIN_CHARS}）。
  *
  * @param {string} source - 源码全文
  * @param {object} request - 定位请求
+ * @param {string} [request.intent] - 模糊意图地址（符号名片段 / 短语 / 近似原文）
  * @param {string} [request.target] - 符号名（`name` / `kind:name` / `Outer/Inner` / `name#n`）
  * @param {{start:number,end:number}} [request.lines] - 1-based 闭区间行号
  * @param {string} [request.lineCue] - 一个词的线索，必须全文件唯一
@@ -114,7 +118,7 @@ function failure(code, message, candidates) {
     return {
       ...c,
       line: typeof c.startLine === 'number' ? c.startLine : null,
-      ...(c.kind === undefined ? {} : { text: `${c.kind}${c.enclosing === undefined ? '' : ` in ${c.enclosing}`}` }),
+      ...(c.kind === undefined ? {} : { text: `${c.kind}${c.enclosing === undefined || c.enclosing === null ? '' : ` in ${c.enclosing}`}` }),
       ordinal: i + 1,
     }
   })
@@ -149,14 +153,25 @@ function failure(code, message, candidates) {
 function renderCandidates(rows) {
   const parts = []
   let spent = 0
+  /**
+   * `target=name#n` 的 `n` 必须是**同名的序号**，不是整份候选列表的序号：
+   * `resolveTarget` 把 `#n` 解释为该名字的第 n 个命中。旧代码拿全局下标，于是
+   * `fooHandler#1, barHandler#2, handler2#3, handler2#4` 里只有第一个能解析——
+   * 其余会把调用方引向 `STRUCT_NOT_FOUND`。唯一名字直接给 `target=name`，不带 `#`。
+   */
+  const nameCounts = new Map()
+  for (const c of rows) if (c.name !== undefined) nameCounts.set(c.name, (nameCounts.get(c.name) ?? 0) + 1)
+  const seen = new Map()
   for (const c of rows) {
+    let nth = null
+    if (c.name !== undefined) {
+      nth = (seen.get(c.name) ?? 0) + 1
+      seen.set(c.name, nth)
+    }
     if (parts.length >= CANDIDATE_LIMIT) break
     const at = typeof c.line === 'number' ? c.line : null
-    const entry =
-      `line ${c.line}${c.text === undefined ? '' : ` = ${quoteForMessage(c.text, at)}`}` +
-      // 符号候选额外给出**可直接用的地址**：`#N` 就是 hits 里的序号（`resolveTarget` 的语义）。
-      // 不给的话，模型只能看见“matched 2 symbols”，而不知道下一步该写什么。
-      (c.name === undefined ? '' : ` (target=${c.name}#${c.ordinal})`)
+    const address = c.name === undefined ? '' : nameCounts.get(c.name) > 1 ? ` (target=${c.name}#${nth})` : ` (target=${c.name})`
+    const entry = `line ${c.line}${c.text === undefined ? '' : ` = ${quoteForMessage(c.text, at)}`}${address}`
     /**
      * 第一条**无论多长都要放**：一条候选都不印的清单等于没给，"有候选"当场变成一句空话。
      * 预算只从第二条起生效。
@@ -240,7 +255,7 @@ const DEFAULT_HINT_CHARS = 7600
  *
  * ## 行号前缀为什么是 `N| ` 而不是读回执的 `N: `
  *
- * 行号用的是**读回执同一套编号**（1-based，与 `aura_read` 打印的行号、与回执开头那句
+ * 行号用的是**读回执同一套编号**（1-based，与 `aura_basetools_read` 打印的行号、与回执开头那句
  * `lines A-B` 同一个尺子），调用方因此能把引文与读回执逐行对上。
  * 字形却刻意**不同形**：`N: ` 正是调用方会整块抄走的那种形状（`probes/quote-hygiene.mjs`
  * 把"行首 `数字: `"列为一类引文污染，且"整块抄走必然失配"），同形等于引诱它连前缀一起抄。
@@ -630,10 +645,52 @@ function assertVerdict(lines, startLine, endLine, tier, actual, assertText) {
 }
 
 /**
- * 定位一个区间。四层降级：符号身份 → 行号 → 唯一词 → 文本锚点。
+ * 意图地址（T16）的符号子串匹配：这个候选符号离 `near` 有多远。
+ *
+ * 判据只有一条：**`near` 落在符号的跨度里就是 0**，否则取到两端中较近的那一端。
+ * 与 `resolveTarget` 的 `|startLine - near|` 刻意不同：`intent` 匹配的是"大概想改哪个符号"，
+ * 调用方给的 `near` 常常是**符号体内**的一行（它刚从 read 回执里抄来），拿起点算距离会把
+ * 一个明显在说的符号判成第二近。跨度包含 `near` ⇒ 距离 0，是这里唯一能自洽的口径。
+ *
+ * @param - 符号投影（含 startLine / endLine）
+ * @param near - 1-based 行号提示
+ * @returns 非负整数距离
+ */
+function symbolDistanceFrom(symbol, near) {
+  if (near >= symbol.startLine && near <= symbol.endLine) return 0
+  return Math.min(Math.abs(near - symbol.startLine), Math.abs(near - symbol.endLine))
+}
+
+/**
+ * 多个子串命中里，`near` 能否**严格**收敛到一个（唯一最小值）。
+ *
+ * 不唯一（并列最小）⇒ null：那正是"该报歧义"的形状，猜测在这里比拒绝贵得多。
+ * @returns 命中的符号，或 null（near 没给 / 并列）
+ */
+function nearestSymbolBySpan(symbols, near) {
+  let best = null
+  let bestDistance = Infinity
+  let ties = 0
+  for (const symbol of symbols) {
+    const distance = symbolDistanceFrom(symbol, near)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = symbol
+      ties = 1
+    } else if (distance === bestDistance) ties += 1
+  }
+  return ties === 1 ? best : null
+}
+
+/**
+ * 定位一个区间。五层降级：意图 → 符号身份 → 行号 → 唯一词 → 文本锚点。
+ *
+ * `intent`（T16）是**最弱但最自然**的一层：调用方给一个符号名片段、短语或近似原文，
+ * 引擎先当符号名解析（精确/限定写法），再按符号名子串匹配，最后才落到文本匹配。
+ * 每一档都**确定性地**收敛到一个区间；收敛不了就报歧义并给候选，不猜。
  *
  * @param source - 文件全文
- * @param request - `target` / `lines` / `lineCue` / `anchor` 四选一，外加 `near` 与 `assert`
+ * @param request - `intent` / `target` / `lines` / `lineCue` / `anchor` 五选一，外加 `near` 与 `assert`
  * @returns 命中时 `{ok: true, startLine, endLine, tier, actual}`；未命中时 `{ok: false, code, message, ...}`。
  *   `actual` 是该区间的原文，供调用方核对或展示。
  */
@@ -647,7 +704,7 @@ export function locate(source, request = {}) {
    * @param byNear - 这次命中是否靠 `near` 从歧义里收敛出来的（见 anchor-core 的四个产出点）。
    *   必须透传：工具回执的 `by near` 标记、以及由此给出的"下次直接用确定地址"建议都靠它。
    *   此前本函数只回 `{startLine, endLine, tier, actual}`，把引擎算好的 `byNear` 丢在中间——
-   *   于是 `aura_edit` 渲染的 `by near` **恒为 false**（字段被声明必填、被渲染、却永远不出现），
+   *   于是 `aura_basetools_edit` 渲染的 `by near` **恒为 false**（字段被声明必填、被渲染、却永远不出现），
    *   降级命中对模型完全不可见。这是本项目最典型的"双义字段/死字段"形态。
    */
   const done = (startLine, endLine, tier, byNear = false) => {
@@ -688,13 +745,161 @@ export function locate(source, request = {}) {
     }
   }
 
+  /**
+   * 符号地址落在“整行区间比声明更宽”的行上 ⇒ 拒绝，不能把行内别的代码一起删掉。
+   *
+   * 这是 `LOCATOR_LINE_SHARED` 的另一半：同族判据（同一行还有别人），但“别人”
+   * 不一定是符号表里的兄弟——`import` / 指令 / 调用语句根本不是符号。
+   */
+  const sharedLineRefusal = (hit, shared, byWhat) => {
+    const label = clipReceiptLabel(filePath === null ? 'this file' : filePath, RECEIPT_LABEL_CHARS)
+    const advice = 'use old= with a unique fragment, handle=, or rewrite the whole file explicitly — nothing was written'
+    const message =
+      shared.side === 'header'
+        ? `cannot address "${hit.name}" by ${byWhat} in ${label}: the declaration starts on line ${shared.line} (${JSON.stringify(shared.text)}), so the addressed span would begin after its header and leave it behind; use lines= covering line ${shared.line}, or ${advice}`
+        : `cannot address "${hit.name}" by ${byWhat} in ${label}: line ${shared.line} also holds ${JSON.stringify(shared.text)} ${shared.side === 'before' ? 'before' : 'after'} the declaration, so replacing the symbol's whole-line span would delete it; ${advice}`
+    return { ok: false, code: 'LOCATOR_LINE_SHARED', message, shared }
+  }
+
+  // ── 第 0 层：意图地址（T16）。调用方给一段模糊的意图串，引擎确定性地落成精确区间。
+  //
+  // 解析次序（每一档都不猜，落不下来就报歧义并给候选）：
+  //   ① 已知语言时，先当符号名解析（`resolveTarget` 的精确 / 限定写法）——命中就算 symbol 档；
+  //   ② 符号名没对上（或对上多个）⇒ 按符号名**子串**匹配（先区分大小写，再忽略大小写）；
+  //   ③ 一个符号都没命中（或语言未知）⇒ 落到文本匹配（`locateWith`，与 `anchor` 同一份引擎）。
+  //
+  // 顺序上刻意在 `target` 之前：`intent` 与其余地址字段**互斥**（`PATCH_INTENT_CONFLICT`，
+  // 由 `planHunks` 判），所以两者同时到达这里是不可能的；放在最前只是把"intent 自成一层"写明。
+  if (typeof request.intent === 'string' && request.intent.trim().length > 0) {
+    const intent = request.intent.trim()
+    const near = request.near ?? null
+    const label = clipReceiptLabel(filePath === null ? 'this file' : filePath, RECEIPT_LABEL_CHARS)
+    /** 跨度覆盖不了符号体时的拒绝——与 `target=` 那一支**同一句话、同一个码**（不是第二套说法）。 */
+    const spanIncomplete = (hit) => ({
+      ok: false,
+      code: 'LOCATOR_SPAN_INCOMPLETE',
+      message: `cannot address "${hit.name}" by intent in ${label}: the span does not cover the body — ${hit.spanNote}; address it with lines= or line_cue= instead`,
+      hint: directoryHint(source, lang),
+    })
+    if (lang !== null) {
+      const index = indexStructure(source, lang)
+      /**
+       * 精确/限定符号：先**不带 near** 解析，拿到唯一命中或完整候选。
+       * 带 near 交给 `resolveTarget` 会用“起点距离”，与 intent 档的“跨度包含 near 记 0”冲突，
+       * 实测会把 near 落在第一个长函数体内的情况选到第二个同名函数上。歧义时这里用
+       * `nearestSymbolBySpan` 按跨度收敛；解析不了再落到子串匹配。
+       */
+      let exact = null
+      try {
+        exact = resolveTarget(index, intent, null)
+      } catch (error) {
+        if (error.code === 'STRUCT_AMBIGUOUS') {
+          const candidates = Array.isArray(error.candidates) ? error.candidates : []
+          if (near !== null && near !== undefined) {
+            const chosen = nearestSymbolBySpan(candidates, near)
+            if (chosen !== null) {
+              if (chosen.spanComplete === false) return spanIncomplete(chosen)
+              return done(chosen.startLine, chosen.endLine, 'intent~symbol', true)
+            }
+          }
+          return failure('LOCATOR_INTENT_AMBIGUOUS', `intent ${JSON.stringify(intent)}: ${error.message}`, candidates)
+        }
+        // STRUCT_NOT_FOUND / 其它：符号名没猜中不是终点，落到子串匹配（下面）。
+      }
+      if (exact !== null) {
+        if (exact.spanComplete === false) return spanIncomplete(exact)
+        const shared = sharedLineContent(source, index, exact, lang)
+        if (shared !== null) return sharedLineRefusal(exact, shared, 'intent')
+        return done(exact.startLine, exact.endLine, 'intent~symbol')
+      }
+      // 用原始符号表而不是 `listSymbols` 投影：整行区间是否越界要看 token，投影里没有。
+      const symbols = index.symbols
+      let matches = symbols.filter((s) => s.name.includes(intent))
+      if (matches.length === 0) {
+        const lower = intent.toLowerCase()
+        matches = symbols.filter((s) => s.name.toLowerCase().includes(lower))
+      }
+      if (matches.length === 1) {
+        const only = matches[0]
+        if (only.spanComplete === false) return spanIncomplete(only)
+        const shared = sharedLineContent(source, index, only, lang)
+        if (shared !== null) return sharedLineRefusal(only, shared, 'intent')
+        return done(only.startLine, only.endLine, 'intent~symbol')
+      }
+      if (matches.length > 1) {
+        if (near !== null && near !== undefined) {
+          const chosen = nearestSymbolBySpan(matches, near)
+          if (chosen !== null) {
+            if (chosen.spanComplete === false) return spanIncomplete(chosen)
+            const shared = sharedLineContent(source, index, chosen, lang)
+            if (shared !== null) return sharedLineRefusal(chosen, shared, 'intent')
+            return done(chosen.startLine, chosen.endLine, 'intent~symbol', true)
+          }
+        }
+        const why =
+          near === null || near === undefined
+            ? `intent ${JSON.stringify(intent)} matched ${matches.length} symbols — pick one with target=<name>, or add near=<line>`
+            : `intent ${JSON.stringify(intent)} matched ${matches.length} symbols and near=${near} did not single one out`
+        return failure(
+          'LOCATOR_INTENT_AMBIGUOUS',
+          why,
+          matches.map((s) => ({
+            name: s.name,
+            kind: s.kind,
+            startLine: s.startLine,
+            endLine: s.endLine,
+            enclosing: s.enclosing,
+          })),
+        )
+      }
+    }
+    // ── ③ 文本兜底：与 `anchor` 同一份引擎（`locateWith`）；tier 里带上它命中的那一档
+    try {
+      const loc = locateWith(indexFile(source), intent, near)
+      return done(loc.start + 1, loc.end, `intent~text~${loc.tier}`, loc.byNear === true)
+    } catch (error) {
+      if (error.code === 'PATCH_AMBIGUOUS') {
+        /**
+         * 行候选统一成 `{line, text}`（`failure` 只认这一形状才会印出行号与原文）：
+         * `locateWith` 抛的是 `number[]`，直接递下去会印成 `line undefined`。
+         */
+        const listed = (Array.isArray(error.candidates) ? error.candidates : [])
+          .filter((n) => typeof n === 'number' && n >= 1 && n <= lines.length)
+          .map((n) => ({ line: n, text: lines[n - 1].slice(0, 80) }))
+        return failure('LOCATOR_INTENT_AMBIGUOUS', `intent ${JSON.stringify(intent)}: ${error.message}`, listed)
+      }
+      if (error.code === 'PATCH_NOT_FOUND' || error.code === 'PATCH_EMPTY_ANCHOR') {
+        return {
+          ok: false,
+          code: 'LOCATOR_INTENT_NOT_FOUND',
+          message: `no symbol or text matches intent ${JSON.stringify(intent)} in ${label}; try target=<name>, lines=, or line_cue=`,
+          // 符号目录是实测支撑的恢复路径（与 anchor 失败同一条）：只有认识这门语言时才给得出。
+          ...(lang === null ? {} : { hint: directoryHint(source, lang) }),
+        }
+      }
+      return failure(error.code ?? 'LOCATOR_FAILED', error.message, error.candidates)
+    }
+  }
+
   // ── 第 1 层：符号身份。不读文本，因此对内容记错免疫。
   if (typeof request.target === 'string' && request.target.trim().length > 0) {
     if (lang === null) {
       return { ok: false, code: 'LOCATOR_NO_LANGUAGE', message: 'target= needs a recognized file extension' }
     }
+    /**
+     * lone CR：符号索引按 `\n` 数行，老式 Mac 文件整份是“一行”，`target` 落成 1-1 后
+     * 会把整个文件替换成一个符号。行号地址在这种情况下没有第二个行模型可校验，
+     * 必须在定位前拒绝，而不是用错误的行号去改。
+     */
+    if (hasLoneCarriageReturn(source)) {
+      return failure(
+        'LOCATOR_LONE_CR',
+        `cannot address "${request.target}" by target in ${clipReceiptLabel(filePath, RECEIPT_LABEL_CHARS)}: this file uses lone CR (\\r) line endings, so line/span addresses point at different bytes than a \\n line model; use old= (verbatim fragment) or handle=, or rewrite the whole file explicitly — nothing was written`,
+      )
+    }
     try {
-      const hit = resolveTarget(indexStructure(source, lang), request.target, request.near ?? null)
+      const index = indexStructure(source, lang)
+      const hit = resolveTarget(index, request.target, request.near ?? null)
       /**
        * 跨度覆盖不了符号体时必须**拒绝**，不能退化成"只有签名行"。
        *
@@ -710,6 +915,25 @@ export function locate(source, request = {}) {
           hint: directoryHint(source, lang),
         }
       }
+      /**
+       * 同一行还有**同级符号** ⇒ `target` 落到的整行区间会连它一起删掉。
+       * 压缩代码里两个顶层函数同为 1-1 是实测形态；名字命中不代表“只改这个名字”。
+       */
+      const siblings = siblingSymbolsOnSameSpan(index, hit)
+      if (siblings.length > 0) {
+        const names = siblings.map((s) => `${s.kind} ${s.name} (line ${s.startLine})`).join(', ')
+        return {
+          ...failure(
+            'LOCATOR_LINE_SHARED',
+            `cannot address "${hit.name}" by target in ${clipReceiptLabel(filePath, RECEIPT_LABEL_CHARS)}: line ${hit.startLine} also holds ${names}, so replacing the symbol's whole-line span would delete them; use old= with a unique fragment, handle=, or rewrite the whole file explicitly — nothing was written`,
+            siblings.map((s) => ({ name: s.name, kind: s.kind, enclosing: s.enclosing, startLine: s.startLine, endLine: s.endLine })),
+          ),
+          hint: directoryHint(source, lang),
+        }
+      }
+      /** 兄弟符号之外，行内还可能有 `import` / 指令 / 调用语句：同一个判据，看字节。 */
+      const shared = sharedLineContent(source, index, hit, lang)
+      if (shared !== null) return sharedLineRefusal(hit, shared, 'target')
       return done(hit.startLine, hit.endLine, 'symbol')
     } catch (error) {
       return {
@@ -723,6 +947,17 @@ export function locate(source, request = {}) {
   if (request.lines !== undefined && request.lines !== null) {
     const start = request.lines.start
     const end = request.lines.end ?? request.lines.start
+    /**
+     * 只有**显式整份写**（`aura_basetools_write` 的内部 wholeFile 请求）能越过 lone CR 闸：
+     * 它替换的是整个文件的字节，不依赖行号模型。普通 `lines=[1,1]` 仍拒绝。
+     */
+    const wholeFile = request.allowLoneCr === true && start === 1 && end === lines.length
+    if (!wholeFile && hasLoneCarriageReturn(source)) {
+      return failure(
+        'LOCATOR_LONE_CR',
+        `cannot address lines ${start}-${end} in ${clipReceiptLabel(filePath, RECEIPT_LABEL_CHARS)}: this file uses lone CR (\\r) line endings, so line numbers do not describe the bytes a \\n line model sees; use old= (verbatim fragment) or handle=, or rewrite the whole file explicitly — nothing was written`,
+      )
+    }
     if (!Number.isInteger(start) || !Number.isInteger(end)) {
       return { ok: false, code: 'LOCATOR_BAD_LINES', message: 'lines.start / lines.end must be integers' }
     }
@@ -785,15 +1020,15 @@ export function locate(source, request = {}) {
       return {
         ...failure(error.code ?? 'LOCATOR_FAILED', error.message, error.candidates),
         // 锚点失败时给出符号目录——这是实测支撑的恢复路径。
-        // 注：`hint` 走的是结构化字段，只有把它拼进 message 的调用方（如 aura_edit
-        // 的 symbolHint）才真能让模型看到；aura_read 直接透传 message，所以真正
+        // 注：`hint` 走的是结构化字段，只有把它拼进 message 的调用方（如 aura_basetools_edit
+        // 的 symbolHint）才真能让模型看到；aura_basetools_read 直接透传 message，所以真正
         // 抵达模型的是上面那条 message。
         ...(lang === null ? {} : { hint: directoryHint(source, lang) }),
       }
     }
   }
 
-  return { ok: false, code: 'LOCATOR_NO_REQUEST', message: 'provide one of: target, lines, lineCue, anchor' }
+  return { ok: false, code: 'LOCATOR_NO_REQUEST', message: 'provide one of: intent, target, lines, lineCue, anchor' }
 }
 
 /**
@@ -809,10 +1044,154 @@ export function locate(source, request = {}) {
  * @returns 追加到错误消息后的说明；不含单 `\r` 时为空串
  */
 function loneCarriageReturnNote(source) {
-  if (!/\r(?!\n)/.test(source)) return ''
+  if (!hasLoneCarriageReturn(source)) return ''
   return ' — this file uses lone CR (\\r) line endings, which are not treated as line breaks here (the symbol index counts lines by \\n, so a second line model would point at different bytes); address it with line_cue/anchor, or replace the whole file with lines=[1,1]'
 }
 
+/** 声明前缀里本来就属于声明的标点（指针/引用/泛型/命名空间/可空修饰）。 */
+const DECL_PREFIX_PUNCT = new Set(['*', '&', '<', '>', ',', '::', '?', ':', '~', '.'])
+
+/** 允许“包住声明”的开括号：Lisp 族的 `(defn …)`。`{` 不算（JS/C 的块不是声明本身）。 */
+const FORM_OPENERS = new Map([['(', ')'], ['[', ']']])
+
+/**
+ * 整行替换会把声明之外的内容一起删掉的那些行。
+ *
+ * `siblingSymbolsOnSameSpan` 只看得见符号表里的兄弟；`import` / 指令 / 调用语句
+ * 根本不是符号，却同样会被整行替换删掉（实测：`import fs from 'fs'; function alpha()`
+ * 上 `target=alpha` 会把 import 一起删掉）。判据回到字节：
+ *   · 声明起点之前：只允许空白与**包住这个声明**的开括号（Lisp 族的 `(defn …)`）；
+ *   · 声明终点之后：只允许空白、分号、注释与包住这个声明的闭括号。
+ * 其余任何 token（`import` / `return` / 另一条语句）都说明这一个行区间不止这个声明。
+ *
+ * @returns `{line, side:'before'|'after'|'header', text}`，或 null（这一行只属于这个声明）
+ */
+function sharedLineContent(source, index, hit, lang) {
+  const declStartTok = hit.declStartTok ?? hit.startTok
+  const startToken = index.tokens[declStartTok]
+  const endToken = index.tokens[hit.endTok]
+  if (startToken === undefined || endToken === undefined) return null
+  const startLine = index.lineAt(startToken.start)
+  /**
+   * C 家族：`$ident*` 吃不掉关键字返回类型，声明起点可能落在名字上（见 struct-core 的
+   * `declStartUnknown`）。类型回到上一行时，行区间会把上一行留成悬空前缀——拒绝，不静默改。
+   * 指令行（`#include`）与注解行（`@Override`）本来就不是声明头，不参与这条判据。
+   */
+  if (hit.declStartUnknown === true) {
+    const prev = index.tokens[(hit.declStartTok ?? hit.startTok) - 1]
+    if (prev !== undefined) {
+      const prevLine = index.lineAt(prev.end)
+      if (prevLine === startLine - 1 && ![';', '{', '}'].includes(prev.value)) {
+        const prevLineStart = source.lastIndexOf('\n', prev.start - 1) + 1
+        const prevLineEnd = source.indexOf('\n', prev.end)
+        const prevLineText = source.slice(prevLineStart, prevLineEnd === -1 ? source.length : prevLineEnd)
+        if (!/^\s*[#@]/.test(prevLineText)) {
+          return { line: prevLine, side: 'header', text: prevLineText.trim().slice(0, 80) }
+        }
+      }
+    }
+  }
+  /**
+   * 声明起点之前、同一行里的 token。只有两类可以留：
+   *   · **类型前缀**——仅当 `declStartUnknown`（C 家族把返回类型漏在声明起点之前）；
+   *   · **包住声明的开括号**（Lisp 族）：它的闭括号会在后缀里出现。
+   * 其余任何 token（`;` / `{` / `=` / 字符串 / `@` / 别的语句）都说明这一行不止这个声明。
+   */
+  const allowTypePrefix = hit.declStartUnknown === true
+  const enclosing = new Map()
+  for (let k = declStartTok - 1; k >= 0; k -= 1) {
+    const token = index.tokens[k]
+    if (index.lineAt(token.start) !== startLine) break
+    if (allowTypePrefix && token.type === 'ident') continue
+    if (allowTypePrefix && token.type === 'punct' && DECL_PREFIX_PUNCT.has(token.value)) continue
+    if (token.type === 'punct' && FORM_OPENERS.has(token.value)) {
+      // `close > endTok` 或 `close === endTok`：Lisp 的收尾 `)` 本身常是跨度的最后一个 token
+      // （`(defn alpha [] 1)` 的 endTok 就是那个 `)`），开括号却仍在跨度之前。
+      const close = index.pairs.get(k)
+      if (close !== undefined && close >= hit.endTok) {
+        const closer = FORM_OPENERS.get(token.value)
+        enclosing.set(closer, (enclosing.get(closer) ?? 0) + 1)
+        continue
+      }
+    }
+    const lineStart = source.lastIndexOf('\n', startToken.start - 1) + 1
+    return { line: startLine, side: 'before', text: source.slice(lineStart, startToken.start).trim().slice(0, 80) }
+  }
+  const endLine = index.lineAt(endToken.end)
+  const lineEnd = source.indexOf('\n', endToken.end)
+  const after = source.slice(endToken.end, lineEnd === -1 ? source.length : lineEnd)
+  const rest = trailingForeign(after, lang, enclosing)
+  if (rest !== '') return { line: endLine, side: 'after', text: rest.trim().slice(0, 80) }
+  return null
+}
+
+/**
+ * 声明终点之后同一行里还剩什么：空白、分号、注释、以及**包住声明的**闭括号不算别的代码。
+ * 闭括号只在 `enclosing` 计数里出现（由前缀里那些开括号登记），所以 `function inner(){} }`
+ * 这种“外层块的 `}` 落在同一行”不会被当成收尾。
+ *
+ * @returns 剩下的非平凡文本（空串 = 这一行到此为止只属于这个声明）
+ */
+function trailingForeign(text, lang, enclosing) {
+  let rest = text
+  const lineComments = lang?.lineComments ?? []
+  const blockComments = lang?.blockComments ?? []
+  for (;;) {
+    rest = rest.replace(/^\s+/, '')
+    if (rest === '') return ''
+    if (lineComments.some((marker) => rest.startsWith(marker))) return ''
+    const block = blockComments.find(([open]) => rest.startsWith(open))
+    if (block !== undefined) {
+      const close = rest.indexOf(block[1], block[0].length)
+      if (close === -1) return rest
+      rest = rest.slice(close + block[1].length)
+      continue
+    }
+    // 分号单独处理：JS 家族是语句分隔符，Lisp 族已经在 lineComments 里提前返回。
+    if (rest.startsWith(';')) {
+      rest = rest.slice(1)
+      continue
+    }
+    const closer = rest[0]
+    const count = enclosing.get(closer) ?? 0
+    if (count > 0) {
+      enclosing.set(closer, count - 1)
+      rest = rest.slice(1)
+      continue
+    }
+    return rest
+  }
+}
+
+/** 文件是否含**不跟 LF** 的 CR（老式 Mac 行尾）。只扫一次、不建第二套行模型。 */
+function hasLoneCarriageReturn(source) {
+  return /\r(?!\n)/.test(source)
+}
+
+/**
+ * 同一行里的**同级符号**（会随整行替换一起消失的那些）。
+ *
+ * 符号投影只有行号、没有列；`target` 最终落到 `[startLine, endLine]` 整行区间。
+ * 压缩代码里两个顶层函数同为 1-1 时，`target=alpha` 会静默删掉 `beta` —— 这是
+ * “名字命中但实际替换整行”的最坏形态。这里只比较**同一 enclosing** 的符号：
+ * 函数体内的局部变量（enclosing 指向函数）不算，否则每个单行函数都会被自己的变量误伤。
+ */
+function siblingSymbolsOnSameSpan(index, hit) {
+  const scope = hit.enclosing ?? null
+  return index.symbols.filter((symbol) => {
+    if ((symbol.enclosing ?? null) !== scope) return false
+    if (
+      symbol.name === hit.name &&
+      symbol.kind === hit.kind &&
+      symbol.startLine === hit.startLine &&
+      symbol.endLine === hit.endLine
+    ) {
+      return false
+    }
+    return symbol.startLine <= hit.endLine && symbol.endLine >= hit.startLine
+  })
+}
+
 /**
  * 符号目录：失败时给调用方一条可执行的恢复路径。
  *