aura-basetools 0.13.0 → 0.13.2

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.13.0
+# aura-basetools 0.13.2
 
 Byte-exact file tools for coding agents: read by intent, edit by intent, and write whole files without corrupting bytes. One engine shared by a standalone CLI and an MCP server.
 
@@ -21,7 +21,7 @@ The engine is intentionally not a general file manager: it reads and edits UTF-8
 ### Install
 
 ```bash
-npm i -g aura-basetools@0.13.0
+npm i -g aura-basetools@0.13.2
 aura --version
 ```
 
@@ -137,7 +137,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.13.0
+npm i -g aura-basetools@0.13.2
 aura --version
 ```
 

package/bin/aura-mcp.mjs

@@ -13,9 +13,9 @@
  *   aura_basetools_transactions  列出当前工作区写事务
  *
  * 接法（写进各家的 MCP 配置即可）：
- *   codex:        codex mcp add aura -- npx -y --package aura-basetools aura mcp
- *   claude code:  claude mcp add aura -- npx -y --package aura-basetools aura mcp
- *   cursor/zed:   command = "npx", args = ["-y", "--package", "aura-basetools", "aura", "mcp"]
+ *   codex:        codex mcp add aura -- npx -y --package aura-basetools aura basetools mcp
+ *   claude code:  claude mcp add aura -- npx -y --package aura-basetools aura basetools mcp
+ *   cursor/zed:   command = "npx", args = ["-y", "--package", "aura-basetools", "aura", "basetools", "mcp"]
  *
  * 为什么必须带 `--package`：本包有两个 bin（`aura` / `aura-mcp`），**没有**一个叫
  * `aura-basetools`；npx 在"多个 bin 且没有与包名同名的"时候会拒绝猜，直接报
@@ -559,7 +559,7 @@ export async function serve() {
   await chain
 }
 
-// 直接运行本文件（`aura-mcp`，package.json 里声明的第二个 bin）也要起服务，与 `aura mcp` 等价。
+// 直接运行本文件（`aura-mcp`，package.json 里声明的第二个 bin）也要起服务，与 `aura basetools mcp` 等价。
 // 用 pathToFileURL 比手拼 file:// 靠得住（Windows 盘符就是那种手拼会踩的地方）。
 if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
   await serve()

package/locator-lab/locator-api.mjs

@@ -745,6 +745,22 @@ 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）。调用方给一段模糊的意图串，引擎确定性地落成精确区间。
   //
   // 解析次序（每一档都不猜，落不下来就报歧义并给候选）：
@@ -792,9 +808,12 @@ export function locate(source, request = {}) {
       }
       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')
       }
-      const symbols = listSymbols(index)
+      // 用原始符号表而不是 `listSymbols` 投影：整行区间是否越界要看 token，投影里没有。
+      const symbols = index.symbols
       let matches = symbols.filter((s) => s.name.includes(intent))
       if (matches.length === 0) {
         const lower = intent.toLowerCase()
@@ -803,6 +822,8 @@ export function locate(source, request = {}) {
       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) {
@@ -810,6 +831,8 @@ export function locate(source, request = {}) {
           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)
           }
         }
@@ -908,6 +931,9 @@ export function locate(source, request = {}) {
           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 {
@@ -1022,6 +1048,121 @@ function loneCarriageReturnNote(source) {
   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)

package/locator-lab/struct-core.mjs

@@ -2278,6 +2278,13 @@ function scanBodyOpen(tokens, pairs, endTok, lang, lineAt, kind) {
     const t = tokens[k]
     const prev = tokens[k - 1]
     if (t.type === 'punct' && (t.value === ';' || t.value === '}')) break
+    /**
+     * Lisp 族：声明本身是列表的第一个元素（`(ns alpha.core)`、`(defn f [a] a)`）。
+     * 名字之后遇到收口 `)` 就是**包住这个声明的那对括号**收尾了——后面的 `(`（下一个 form）
+     * 不是块体。少了这一条，`(ns alpha)` 会把下一行 `(defn …)` 的 `(` 当体，跨度扩到整个文件，
+     * `target=alpha` 会连后面的函数一起删掉（lang-coverage 的 cljs 夹具就是这个形状）。
+     */
+    if (open === '(' && t.type === 'punct' && t.value === ')') break
     /**
      * 块开符判定：`bodyOpen` 本身，加上**配置声明的**其它块开符（`[$ … ]` 字面量体），
      * 再加上 `bodyOpens` 里显式列出的字符。
@@ -2390,7 +2397,7 @@ function headerContinues(tokens, k, prev, clauses) {
  * 用独立的第二条规则去做会与变量规则重复命中同一个位置，靠规则顺序决定谁赢，
  * 那是在用"顺序"掩盖语义，典型补丁。
  */
-function declarationSpan(tokens, pairs, startTok, endTok, lang, lineAt, kind, lines, termScan) {
+function declarationSpan(tokens, pairs, declStartTok, startTok, endTok, lang, lineAt, kind, lines, termScan) {
   const open = lang.bodyOpen
   let bodyOpen = null
   let binding = kind
@@ -2456,10 +2463,13 @@ function declarationSpan(tokens, pairs, startTok, endTok, lang, lineAt, kind, li
 
   return {
     kind: binding,
-    startLine: lineAt(tokens[startTok].start),
+    // 声明起点是**规则起点**（含修饰符/返回类型），不是名字 token：`export function\nalpha()`
+    // 若从名字所在行算起，整行替换会把上一行的 `export function` 留成悬空前缀。
+    startLine: lineAt(tokens[declStartTok].start),
     endLine: lineAt(tokens[last].end),
     startTok,
     endTok: last,
+    declStartTok,
     bodyOpen,
     spanComplete,
     spanNote,
@@ -2666,8 +2676,21 @@ function buildStructure(src, lang) {
       // 会捕到参数列表里的 `a:` 这种半截 token 并报出一个不存在的符号。
       // 它比“只捕标识符”的 `$name` 严——`$name` 不校验**字符串**内容，而 `$label` 会带引号进来。
       if (typeof name !== 'string' || !/^[A-Za-z_$\u0080-\uffff][A-Za-z0-9_$\u0080-\uffff-]*$/.test(name)) continue
-      const span = declarationSpan(tokens, pairs, hit.startTok, hit.end - 1, lang, lineAt, rule.kind, lines, termScan)
-      symbols.push({ name, ...span })
+      const span = declarationSpan(tokens, pairs, hit.matchStart, hit.startTok, hit.end - 1, lang, lineAt, rule.kind, lines, termScan)
+      /**
+       * 规则在名字之前只有 `$mods*` / `$ident*` 这类“可选前缀段”、没有字面量时，匹配器可能
+       * 一段都没吃到：C 的 `static int alpha`（`$ident*` 只吃非关键字，`int` 是关键字）、
+       * Dart 的 `int alpha(...)`（规则是 `$mods* $name …`，返回类型不在模式里）。此时
+       * `declStartTok` 落在名字上，类型若回到**上一行**，行区间会把上一行留成悬空前缀。
+       *
+       * 这里只做标记，判据放在定位层（{@link sharedLineContent}）：它能看到行文本与上一行
+       * 是否真的像声明头。`matchStart !== startTok` 说明前缀已经被吃进跨度，没有这个盲区。
+       */
+      const nameAt = rule.pattern.findIndex((part) => part === '$name' || part === '$nameNotKeyword')
+      const prefixParts = nameAt > 0 ? rule.pattern.slice(0, nameAt) : []
+      const declStartUnknown =
+        hit.matchStart === hit.startTok && prefixParts.length > 0 && prefixParts.every((part) => part.startsWith('$'))
+      symbols.push({ name, ...span, ...(declStartUnknown ? { declStartUnknown: true } : {}) })
       break
     }
   }

package/locator-lab/write-path.mjs

@@ -2803,6 +2803,8 @@ export function planHunks(content, hunks, filePath = null, options = {}) {
       if (!found.ok) {
         throw new PatchError(found.message, found.code, {
           ...(found.candidates === undefined ? {} : { candidates: found.candidates }),
+          /** `LOCATOR_LINE_SHARED` 的“被谁占了”证据（符号兄弟之外的 import/尾随语句）。 */
+          ...(found.shared === undefined ? {} : { shared: found.shared }),
         })
       }
       hits = [{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-basetools",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Byte-exact read, edit and write tools for coding agents. Standalone CLI and MCP server; no DSH required. 面向 coding agent 的逐字节读写工具；独立 CLI / MCP，可选 DSH 适配器。",
   "license": "MIT",
   "type": "module",