autosnippet 3.0.11 → 3.0.13

package/lib/platform/ios/xcode/XcodeIntegration.js

@@ -13,267 +13,26 @@
  *   §9  完整插入流程   — cut 触发行 → preflight → headers → offset → paste
  */
 
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, resolve as pathResolve, relative, sep } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { saveEventFilter } from './SaveEventFilter.js';
 
-// ═══════════════════════════════════════════════════════════════
-// §1 常量与工具函数
-// ═══════════════════════════════════════════════════════════════
-
-function _sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * 在 import 行末尾附加来源标记注释
- */
-function _withAutoSnippetNote(importLine) {
-  if (!importLine) {
-    return importLine;
-  }
-  const note = '// AutoSnippet: 自动插入';
-  if (importLine.includes(note)) {
-    return importLine;
-  }
-  return `${importLine} ${note}`;
-}
-
-/**
- * 解析原始 header 字符串，提取 moduleName 和 headerName
- *
- * 支持格式：
- *   #import <Module/Header.h>  → { moduleName: 'Module', headerName: 'Header.h', isAngle: true }
- *   #import "Header.h"          → { moduleName: '', headerName: 'Header.h', isAngle: false }
- *   @import Module;             → { moduleName: 'Module', headerName: '', isAngle: false, isAtImport: true }
- *   import Module (Swift)       → { moduleName: 'Module', headerName: '', isAngle: false, isSwiftImport: true }
- *   Header.h                    → { moduleName: '', headerName: 'Header.h', isAngle: false, isRaw: true }
- */
-function _parseHeaderString(header) {
-  const t = header.trim();
-  // #import <Module/Header.h>
-  let m = t.match(/^#(?:import|include)\s+<([^/> ]+)\/([^>]+)>/);
-  if (m) {
-    return { moduleName: m[1], headerName: m[2], isAngle: true };
-  }
-  // #import <Module>  (framework umbrella)
-  m = t.match(/^#(?:import|include)\s+<([^>]+)>/);
-  if (m) {
-    return { moduleName: m[1], headerName: '', isAngle: true };
-  }
-  // #import "Header.h" or #import "Dir/Header.h"
-  m = t.match(/^#(?:import|include)\s+"([^"]+)"/);
-  if (m) {
-    const parts = m[1].split('/');
-    return {
-      moduleName: '',
-      headerName: parts[parts.length - 1],
-      isAngle: false,
-      quotedPath: m[1],
-    };
-  }
-  // @import Module;
-  m = t.match(/^@import\s+(\w+)/);
-  if (m) {
-    return { moduleName: m[1], headerName: '', isAngle: false, isAtImport: true };
-  }
-  // import Module (Swift)
-  m = t.match(/^import\s+(\w+)/);
-  if (m && !['class', 'struct', 'enum', 'protocol', 'func', 'var', 'let'].includes(m[1])) {
-    return { moduleName: m[1], headerName: '', isAngle: false, isSwiftImport: true };
-  }
-  // 裸 header 名: Header.h
-  if (/\.(h|hpp|hh)$/i.test(t)) {
-    return { moduleName: '', headerName: t, isAngle: false, isRaw: true };
-  }
-  return { moduleName: '', headerName: t, isAngle: false, isRaw: true };
-}
-
-/**
- * 在 target 源目录中搜索头文件，返回相对于当前文件的路径
- *
- * 搜索策略：
- *   1. 当前文件同目录
- *   2. 从项目根目录递归查找（最多深度 6 层，优先 Sources/ 下）
- *   3. 找到后计算相对于当前文件目录的路径
- *
- * @param {string} headerName - 头文件名 (如 "Foo.h")
- * @param {string} currentFilePath - 当前正在编辑的文件绝对路径
- * @param {string} [projectRoot] - 项目根目录
- * @returns {string|null} 相对路径 (如 "Foo.h" 或 "../SubDir/Foo.h")，null 表示未找到
- */
-function _findHeaderRelativePath(headerName, currentFilePath, projectRoot) {
-  if (!headerName || !currentFilePath) {
-    return null;
-  }
-  try {
-    const currentDir = dirname(currentFilePath);
-
-    // 1. 同目录检查
-    const sameDir = pathResolve(currentDir, headerName);
-    if (existsSync(sameDir)) {
-      return headerName;
-    }
-
-    // 2. 向上找 Sources/ 或 target 根目录，在其下递归搜索
-    const searchRoots = [];
-    if (projectRoot) {
-      const sourcesDir = pathResolve(projectRoot, 'Sources');
-      if (existsSync(sourcesDir)) {
-        searchRoots.push(sourcesDir);
-      }
-      searchRoots.push(projectRoot);
-    }
-    // 也从当前文件向上找 Sources 目录
-    let dir = currentDir;
-    for (let i = 0; i < 8; i++) {
-      const base = basename(dir);
-      if (base === 'Sources' || base === 'Source' || base === 'src') {
-        searchRoots.unshift(dir);
-        break;
-      }
-      const parent = dirname(dir);
-      if (parent === dir) {
-        break;
-      }
-      dir = parent;
-    }
-
-    // 在 searchRoots 中递归查找 headerName（限深度 6）
-    for (const root of searchRoots) {
-      const found = _findFileRecursive(root, headerName, 6);
-      if (found) {
-        let rel = relative(currentDir, found);
-        // 统一用 / 分隔
-        rel = rel.split(sep).join('/');
-        return rel;
-      }
-    }
-
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 递归查找文件（限最大深度）
- */
-function _findFileRecursive(dir, fileName, maxDepth) {
-  if (maxDepth <= 0) {
-    return null;
-  }
-  try {
-    const entries = readdirSync(dir);
-    // 先在当前层查找
-    for (const e of entries) {
-      if (e === fileName) {
-        return pathResolve(dir, e);
-      }
-    }
-    // 再递归子目录（跳过隐藏目录和常见无关目录）
-    for (const e of entries) {
-      if (e.startsWith('.') || e === 'node_modules' || e === 'build' || e === 'DerivedData') {
-        continue;
-      }
-      const full = pathResolve(dir, e);
-      try {
-        if (statSync(full).isDirectory()) {
-          const found = _findFileRecursive(full, fileName, maxDepth - 1);
-          if (found) {
-            return found;
-          }
-        }
-      } catch {
-        /* 跳过不可访问的目录 */
-      }
-    }
-  } catch {
-    /* 跳过不可读目录 */
-  }
-  return null;
-}
-
-/**
- * 根据当前文件 target 和 header 的 module 关系，生成正确格式的 import 行
- *
- * 规则:
- *   Swift: 始终 `import Module`（无 quote/angle 区别）
- *   ObjC 同 target:  `#import "Header.h"` （引号格式）
- *   ObjC 跨 target:  `#import <Module/Header.h>` （尖括号格式）
- *   @import 格式保持原样（已经模块级）
- *
- * @param {string} rawHeader  原始 header 字符串
- * @param {object} ctx        { currentTarget, headerModuleName, isSwift, fullPath, projectRoot }
- *   - currentTarget:    当前文件所属的 target 名
- *   - headerModuleName: header 所属的 module/target 名（来自 recipe.moduleName 或推断）
- *   - isSwift:          目标文件是否是 Swift
- *   - fullPath:         当前编辑文件的绝对路径（用于计算同 target 相对路径）
- *   - projectRoot:      项目根目录（用于搜索头文件物理位置）
- * @returns {string} 格式化后的完整 import 行
- */
-function _resolveHeaderFormat(rawHeader, ctx) {
-  const { currentTarget, headerModuleName, isSwift, fullPath, projectRoot } = ctx;
-  const parsed = _parseHeaderString(rawHeader);
-
-  // Swift: 始终 `import Module`
-  if (isSwift || parsed.isSwiftImport) {
-    // 已经是完整 swift import 语句
-    if (parsed.isSwiftImport) {
-      return rawHeader.trim();
-    }
-    // 从 ObjC 格式推断 swift import
-    const mod = parsed.moduleName || headerModuleName || '';
-    if (mod) {
-      return `import ${mod}`;
-    }
-    return rawHeader.trim(); // 无法推断，原样返回
-  }
-
-  // @import 保持原样（模块级引用不受 target 影响）
-  if (parsed.isAtImport) {
-    return rawHeader.trim();
-  }
-
-  // 已经是尖括号格式 → 保持（明确的跨模块引用）
-  if (parsed.isAngle) {
-    return rawHeader.trim();
-  }
-
-  // ── ObjC: 判断同 target vs 跨 target ──
-  const effectiveModule = parsed.moduleName || headerModuleName || '';
-
-  // 如果没有 target 信息，无法判断，保持原样
-  if (!currentTarget || !effectiveModule) {
-    return rawHeader.trim();
-  }
-
-  const isSameTarget = currentTarget === effectiveModule;
-
-  if (isSameTarget) {
-    // 同 target → 引号格式，计算相对路径
-    if (parsed.headerName && fullPath) {
-      const relPath = _findHeaderRelativePath(parsed.headerName, fullPath, projectRoot);
-      if (relPath) {
-        return `#import "${relPath}"`;
-      }
-    }
-    if (parsed.quotedPath) {
-      return `#import "${parsed.quotedPath}"`;
-    }
-    if (parsed.headerName) {
-      return `#import "${parsed.headerName}"`;
-    }
-    return rawHeader.trim();
-  }
-
-  // 跨 target → 尖括号格式 <Module/Header.h>
-  if (parsed.headerName) {
-    return `#import <${effectiveModule}/${parsed.headerName}>`;
-  }
-  // 没有 headerName（裸模块名），用 @import
-  return `@import ${effectiveModule};`;
-}
+import {
+  resolveHeaderFormat,
+  collectImportsFromFile,
+  collectImportsFromHeaderFile,
+  checkImportStatus,
+  inferModulesFromHeaders,
+} from './XcodeImportResolver.js';
+
+import {
+  sleep,
+  withAutoSnippetNote,
+  evaluateDepResult,
+  handleDepReview,
+  writeImportLineXcode,
+  writeImportLineFile,
+  computePasteLineNumber,
+} from './XcodeWriteUtils.js';
 
 /** 常见 Apple 系统框架（无需 SPM 依赖检查） */
 const _SYSTEM_FRAMEWORKS = new Set([
@@ -329,384 +88,6 @@ const _SYSTEM_FRAMEWORKS = new Set([
   'XCTest',
 ]);
 
-// ═══════════════════════════════════════════════════════════════
-// §4 三级 import 去重
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 从文件中收集已有的 import 语句
- */
-function _collectImportsFromFile(filePath, isSwift) {
-  try {
-    if (!existsSync(filePath)) {
-      return [];
-    }
-    const content = readFileSync(filePath, 'utf8');
-    const lines = content.split(/\r?\n/);
-    const imports = [];
-    for (const line of lines) {
-      const t = line.trim();
-      if (isSwift) {
-        if (t.startsWith('import ')) {
-          imports.push(t);
-        }
-      } else {
-        if (t.startsWith('#import ') || t.startsWith('@import ') || t.startsWith('#include ')) {
-          imports.push(t);
-        }
-      }
-    }
-    return imports;
-  } catch {
-    return [];
-  }
-}
-
-/**
- * 收集 .m 文件对应 .h 文件中的 imports（ObjC 接口/实现配对去重）
- */
-function _collectImportsFromHeaderFile(sourcePath, importArray) {
-  const dotIndex = sourcePath.lastIndexOf('.');
-  if (dotIndex <= 0) {
-    return;
-  }
-  const headerPath = `${sourcePath.substring(0, dotIndex)}.h`;
-  const importReg = /^#import\s*<[A-Za-z0-9_]+\/[A-Za-z0-9_+.-]+\.h>$/;
-  try {
-    if (!existsSync(headerPath)) {
-      return;
-    }
-    const data = readFileSync(headerPath, 'utf8');
-    for (const line of data.split('\n')) {
-      const t = line.trim();
-      if (importReg.test(t) && !importArray.includes(t)) {
-        importArray.push(t);
-      }
-    }
-  } catch {
-    /* ignore */
-  }
-}
-
-/**
- * 三级 import 去重检查
- *
- *   hasHeader        精确匹配（同一 import 行）
- *   hasModule        模块级匹配（同模块不同头文件，或 @import）
- *   hasSimilarHeader 文件名 case-insensitive 匹配
- *
- * @param {string[]} importArray 已有的 import 行
- * @param {string}   headerLine 待插入的 import 行
- * @param {boolean}  isSwift
- */
-function _checkImportStatus(importArray, headerLine, isSwift) {
-  const trimmed = headerLine.trim();
-
-  // 提取 module / headerFileName
-  let moduleName = '';
-  let headerFileName = '';
-
-  if (isSwift) {
-    const m = trimmed.match(/^import\s+(\w+)/);
-    if (m) {
-      moduleName = m[1];
-    }
-    headerFileName = moduleName;
-  } else {
-    const angle = trimmed.match(/<([^/]+)\/([^>]+)>/);
-    if (angle) {
-      moduleName = angle[1];
-      headerFileName = angle[2];
-    }
-    const quote = trimmed.match(/"([^"]+)"/);
-    if (quote) {
-      headerFileName = basename(quote[1]);
-    }
-  }
-
-  const headerFileNameLower = headerFileName.toLowerCase();
-
-  for (const imp of importArray) {
-    const impT = imp.trim();
-
-    // ── 级别 1: 精确匹配 ──
-    if (impT === trimmed) {
-      return { hasHeader: true, hasModule: false, hasSimilarHeader: false };
-    }
-    // 去掉可能的 AutoSnippet 注释后缀再比较
-    const impTClean = impT.replace(/\s*\/\/\s*AutoSnippet.*$/, '').trim();
-    if (impTClean === trimmed) {
-      return { hasHeader: true, hasModule: false, hasSimilarHeader: false };
-    }
-
-    if (isSwift) {
-      // ── 级别 2: Swift 模块匹配 ──
-      const m2 = impT.match(/^import\s+(\w+)/);
-      if (m2 && m2[1] === moduleName) {
-        return { hasHeader: false, hasModule: true, hasSimilarHeader: false };
-      }
-    } else {
-      // ── 级别 2: ObjC 模块匹配（<Module/xxx> 或 @import Module） ──
-      if (moduleName) {
-        const impAngle = impT.match(/<([^/]+)\//);
-        if (impAngle && impAngle[1] === moduleName) {
-          return { hasHeader: false, hasModule: true, hasSimilarHeader: false };
-        }
-        const impAt = impT.match(/@import\s+(\w+)/);
-        if (impAt && impAt[1] === moduleName) {
-          return { hasHeader: false, hasModule: true, hasSimilarHeader: false };
-        }
-      }
-
-      // ── 级别 3: 相似头文件名匹配（case-insensitive） ──
-      if (headerFileNameLower) {
-        let importedFileName = null;
-        const a = impT.match(/<[^/]+\/([^>]+)>/);
-        if (a) {
-          importedFileName = a[1].toLowerCase();
-        }
-        const q = impT.match(/"([^"]+)"/);
-        if (q) {
-          importedFileName = basename(q[1]).toLowerCase();
-        }
-        if (importedFileName && importedFileName === headerFileNameLower) {
-          return { hasHeader: false, hasModule: false, hasSimilarHeader: true };
-        }
-      }
-    }
-  }
-
-  return { hasHeader: false, hasModule: false, hasSimilarHeader: false };
-}
-
-// ═══════════════════════════════════════════════════════════════
-// §5 模块名推断
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 从 import 语句推断模块名
- *
- *   #import <Module/Header.h>  → Module
- *   @import Module;            → Module
- *   import Module (Swift)      → Module
- *   #import "Local.h"          → null
- */
-function _inferModulesFromHeaders(headers) {
-  const modules = new Set();
-  for (const h of headers) {
-    const t = h.trim();
-    let m;
-    m = t.match(/^#import\s+<([^/> ]+)/);
-    if (m) {
-      modules.add(m[1]);
-      continue;
-    }
-    m = t.match(/^@import\s+(\w+)/);
-    if (m) {
-      modules.add(m[1]);
-      continue;
-    }
-    m = t.match(/^import\s+(\w+)/);
-    if (m && !['class', 'struct', 'enum', 'protocol'].includes(m[1])) {
-      modules.add(m[1]);
-    }
-  }
-  return [...modules];
-}
-
-// ═══════════════════════════════════════════════════════════════
-// §6 SPM 依赖检查决策引擎
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 将 SpmService.ensureDependency 返回值映射为三种动作：
- *   continue — 依赖已存在
- *   block    — 循环/反向依赖，禁止插入
- *   review   — 依赖缺失但可添加，需用户确认
- */
-function _evaluateDepResult(ensureResult, from, to) {
-  if (ensureResult.exists) {
-    return { action: 'continue' };
-  }
-  if (!ensureResult.canAdd) {
-    return { action: 'block', reason: ensureResult.reason || 'cycleBlocked', from, to };
-  }
-  return { action: 'review', reason: ensureResult.reason || 'missingDependency', from, to };
-}
-
-/**
- * 公共依赖审查弹窗逻辑（insertHeaders 和 _preflightDeps 共享）
- *
- * @param {object} ctx - { spmService, currentTarget, mod, ensureResult, NU, depWarnings, label }
- * @returns {{ blocked: boolean }}
- */
-function _handleDepReview(ctx) {
-  const { spmService, currentTarget, mod, ensureResult, NU, depWarnings, label = '' } = ctx;
-
-  const fixMode = spmService.getFixMode();
-  const buttons =
-    fixMode === 'fix'
-      ? ['直接插入（信任架构）', '提示操作插入', '自动修复依赖', '取消操作']
-      : ['直接插入（信任架构）', '提示操作插入', '取消操作'];
-
-  const crossTag = ensureResult.crossPackage ? ' (跨包)' : '';
-  const prefix = label ? `[${label}] ` : '';
-
-  const userChoice = NU.promptWithButtons(
-    `检测到依赖缺失：${currentTarget} -> ${mod}${crossTag}\n\n请选择处理方式：`,
-    buttons,
-    'AutoSnippet SPM 依赖决策'
-  );
-
-  if (
-    userChoice === '取消操作' ||
-    (!userChoice && !['直接插入（信任架构）', '提示操作插入', '自动修复依赖'].includes(userChoice))
-  ) {
-    return { blocked: true };
-  }
-
-  if (userChoice === '提示操作插入') {
-    depWarnings.set(mod, `${currentTarget} -> ${mod}`);
-  }
-
-  if (userChoice === '自动修复依赖') {
-    const fixResult = spmService.addDependency(currentTarget, mod);
-    if (fixResult.ok) {
-      NU.notify(`已补齐依赖：${currentTarget} -> ${mod}`, 'AutoSnippet SPM');
-    } else {
-      console.warn(`  ⚠️ ${prefix}自动修复失败: ${fixResult.error}，继续插入`);
-      depWarnings.set(mod, `${currentTarget} -> ${mod}`);
-    }
-  }
-
-  return { blocked: false };
-}
-
-// ═══════════════════════════════════════════════════════════════
-// §7 Xcode osascript 单条 import 写入
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 通过 Xcode 自动化插入一条 import，保持 Xcode Undo 可用。
- *
- * 流程：保存剪贴板 → 写入 import 内容 → osascript 跳转+粘贴 → 恢复剪贴板
- *
- * @param {string} importLine  完整的 import 文本
- * @param {number} insertLine  1-based 行号
- * @param {object} XA          XcodeAutomation 模块
- * @param {object} CM          ClipboardManager 模块
- * @returns {boolean}
- */
-function _writeImportLineXcode(importLine, insertLine, XA, CM) {
-  if (!XA.isXcodeRunning()) {
-    return false;
-  }
-  try {
-    const contentToWrite = `${String(importLine).trim()}\n`;
-    const previousClipboard = CM.read();
-
-    CM.write(contentToWrite);
-    const ok = XA.insertAtLineStartInXcode(insertLine);
-
-    // 始终恢复剪贴板
-    if (typeof previousClipboard === 'string') {
-      CM.write(previousClipboard);
-    }
-    return ok;
-  } catch {
-    return false;
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════
-// §8 文件写入回退
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 纯文件写入插入单条 import。
- * Xcode 会因文件变更而自动 reload。
- */
-function _writeImportLineFile(filePath, importLine, isSwift) {
-  try {
-    const content = readFileSync(filePath, 'utf8');
-    const lines = content.split('\n');
-    let lastImportIdx = -1;
-    for (let i = 0; i < lines.length; i++) {
-      const t = lines[i].trim();
-      if (isSwift) {
-        if (t.startsWith('import ') && !t.startsWith('import (')) {
-          lastImportIdx = i;
-        }
-      } else {
-        if (t.startsWith('#import ') || t.startsWith('#include ') || t.startsWith('@import ')) {
-          lastImportIdx = i;
-        }
-      }
-    }
-    const insertAt = lastImportIdx >= 0 ? lastImportIdx + 1 : 0;
-    lines.splice(insertAt, 0, importLine);
-    const newContent = lines.join('\n');
-    saveEventFilter.markWrite(filePath, newContent);
-    writeFileSync(filePath, newContent, 'utf8');
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════
-// §9 粘贴行号偏移计算
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * 查找文件中最后一个 import 行的行号（1-based，0 表示无 import）
- */
-function _getLastImportLine(filePath) {
-  try {
-    if (!existsSync(filePath)) {
-      return 0;
-    }
-    const content = readFileSync(filePath, 'utf8');
-    const lines = content.split(/\r?\n/);
-    let lastIdx = -1;
-    for (let i = 0; i < lines.length; i++) {
-      const t = lines[i].trim();
-      if (
-        t.startsWith('#import ') ||
-        t.startsWith('@import ') ||
-        t.startsWith('#include ') ||
-        t.startsWith('import ')
-      ) {
-        lastIdx = i;
-      }
-    }
-    return lastIdx >= 0 ? lastIdx + 1 : 0;
-  } catch {
-    return 0;
-  }
-}
-
-/**
- * 计算代码粘贴行号
- *
- * 如果 headers 插入在 trigger 行之前（import 区），trigger 行号需要向下偏移。
- */
-function _computePasteLineNumber(triggerLineNumber, headerInsertCount, filePath, options = {}) {
-  const expectedCount = Number.isFinite(options.expectedHeaderCount)
-    ? options.expectedHeaderCount
-    : headerInsertCount;
-  if (expectedCount > 0) {
-    if (options.forceOffset) {
-      return triggerLineNumber + expectedCount;
-    }
-    const headerInsertPosition = _getLastImportLine(filePath);
-    if (headerInsertPosition > 0 && headerInsertPosition < triggerLineNumber) {
-      return triggerLineNumber + expectedCount;
-    }
-  }
-  return triggerLineNumber;
-}
-
 // ═══════════════════════════════════════════════════════════════
 // §10 导出：insertHeaders
 // ═══════════════════════════════════════════════════════════════
@@ -741,10 +122,10 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
   const isSwift = opts.isSwift ?? fullPath.endsWith('.swift');
 
   // ── Step 1: 收集已有 imports ──
-  const importArray = _collectImportsFromFile(fullPath, isSwift);
+  const importArray = collectImportsFromFile(fullPath, isSwift);
   // .m 文件还要收集对应 .h 的 imports
   if (!isSwift && !fullPath.endsWith('.h')) {
-    _collectImportsFromHeaderFile(fullPath, importArray);
+    collectImportsFromHeaderFile(fullPath, importArray);
   }
 
   // ── Step 2: SPM/模块 服务准备 ──
@@ -752,7 +133,7 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
   let spmService = opts._spmService || null;
   let currentTarget = opts._currentTarget || null;
   if (!spmService && !opts.skipDepCheck) {
-    const inferredModules = _inferModulesFromHeaders(headers);
+    const inferredModules = inferModulesFromHeaders(headers);
     if (opts.moduleName && !inferredModules.includes(opts.moduleName)) {
       inferredModules.push(opts.moduleName);
     }
@@ -802,17 +183,17 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
 
     // ── 三级去重 ──
     // 先按原始格式检查，再按解析后格式检查（同一 header 可能格式不同）
-    const preResolvedHeader = _resolveHeaderFormat(headerTrimmed, {
+    const preResolvedHeader = resolveHeaderFormat(headerTrimmed, {
       currentTarget,
       headerModuleName: opts.moduleName || null,
       isSwift,
       fullPath,
       projectRoot: watcher?.projectRoot || null,
     });
-    const status = _checkImportStatus(importArray, headerTrimmed, isSwift);
+    const status = checkImportStatus(importArray, headerTrimmed, isSwift);
     const statusResolved =
       preResolvedHeader !== headerTrimmed
-        ? _checkImportStatus(importArray, preResolvedHeader, isSwift)
+        ? checkImportStatus(importArray, preResolvedHeader, isSwift)
         : status;
     if (status.hasHeader || statusResolved.hasHeader) {
       result.skipped.push(preResolvedHeader);
@@ -828,7 +209,7 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
     }
 
     // ── SPM 依赖检查 ──
-    const headerModules = _inferModulesFromHeaders([headerTrimmed]);
+    const headerModules = inferModulesFromHeaders([headerTrimmed]);
     if (spmService && currentTarget && !opts.skipDepCheck) {
       for (const mod of headerModules) {
         if (_SYSTEM_FRAMEWORKS.has(mod) || mod === currentTarget) {
@@ -836,7 +217,7 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
         }
 
         const ensureResult = spmService.ensureDependency(currentTarget, mod);
-        const decision = _evaluateDepResult(ensureResult, currentTarget, mod);
+        const decision = evaluateDepResult(ensureResult, currentTarget, mod);
 
         if (decision.action === 'block') {
           console.warn(`     ⛔ 依赖被阻止: ${currentTarget} -> ${mod} (${decision.reason})`);
@@ -849,7 +230,7 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
         }
 
         if (decision.action === 'review') {
-          const reviewResult = _handleDepReview({
+          const reviewResult = handleDepReview({
             spmService,
             currentTarget,
             mod,
@@ -870,22 +251,22 @@ export async function insertHeaders(watcher, fullPath, headers, opts = {}) {
     const resolvedHeader = preResolvedHeader;
     const depHint = headerModules.find((m) => depWarnings.has(m));
     const importLine = depHint
-      ? `${_withAutoSnippetNote(resolvedHeader)} // ⚠️ 依赖缺失: ${depWarnings.get(depHint)}，需手动补齐 Package.swift`
-      : _withAutoSnippetNote(resolvedHeader);
+      ? `${withAutoSnippetNote(resolvedHeader)} // ⚠️ 依赖缺失: ${depWarnings.get(depHint)}，需手动补齐 Package.swift`
+      : withAutoSnippetNote(resolvedHeader);
 
     // ── 写入：Xcode 自动化优先 → 文件写入回退 ──
     let inserted = false;
 
     if (xcodeReady && !fileWriteUsed) {
       // 逐条 osascript 跳转 + 粘贴
-      inserted = _writeImportLineXcode(importLine, baseInsertLine + xcodeOffset, XA, CM);
+      inserted = writeImportLineXcode(importLine, baseInsertLine + xcodeOffset, XA, CM);
       if (inserted) {
         xcodeOffset++;
       }
     }
 
     if (!inserted) {
-      _writeImportLineFile(fullPath, importLine, isSwift);
+      writeImportLineFile(fullPath, importLine, isSwift);
       fileWriteUsed = true;
     }
 
@@ -989,7 +370,7 @@ export async function insertCodeToXcode(watcher, fullPath, selected, triggerLine
         skipDepCheck: true,
       });
     }
-    await _sleep(300);
+    await sleep(300);
 
     // ── Step 4: 构建带缩进的代码块 ──
     const codeLines = code.split(/\r?\n/);
@@ -1020,7 +401,7 @@ export async function insertCodeToXcode(watcher, fullPath, selected, triggerLine
     // ── Step 6: 计算偏移后的粘贴行号 ──
     // 使用实际插入的 header 数量计算偏移，而非期望数量
     // 当 headers 全部重复被跳过时，headerInsertCount = 0，不应偏移
-    const pasteLineNumber = _computePasteLineNumber(
+    const pasteLineNumber = computePasteLineNumber(
       triggerLineNumber,
       headerInsertCount,
       fullPath,
@@ -1029,7 +410,7 @@ export async function insertCodeToXcode(watcher, fullPath, selected, triggerLine
 
     // 如果 headers 通过文件写入，等待 Xcode reload
     if (headerInsertCount > 0) {
-      await _sleep(600);
+      await sleep(600);
     }
 
     // ── Step 7: Jump + 选中行内容 + 粘贴替换 ──
@@ -1039,11 +420,11 @@ export async function insertCodeToXcode(watcher, fullPath, selected, triggerLine
         console.warn(`  ⚠️ 剪贴板写入失败`);
         return;
       }
-      await _sleep(100);
+      await sleep(100);
       XA.jumpToLineInXcode(pasteLineNumber);
-      await _sleep(500);
+      await sleep(500);
       XA.selectAndPasteInXcode();
-      await _sleep(300);
+      await sleep(300);
     });
     NU.notify(`已插入「${selected.title || '代码片段'}」`, 'AutoSnippet');
     return;
@@ -1069,7 +450,7 @@ async function _preflightDeps(fullPath, headers, selected, NU) {
   const result = { blocked: false };
 
   // 始终从所有 headers 推断模块（不仅依赖 selected.moduleName）
-  const inferredModules = _inferModulesFromHeaders(headers);
+  const inferredModules = inferModulesFromHeaders(headers);
   if (selected.moduleName && !inferredModules.includes(selected.moduleName)) {
     inferredModules.push(selected.moduleName);
   }
@@ -1108,7 +489,7 @@ async function _preflightDeps(fullPath, headers, selected, NU) {
       }
 
       const ensureResult = spmService.ensureDependency(currentTarget, mod);
-      const decision = _evaluateDepResult(ensureResult, currentTarget, mod);
+      const decision = evaluateDepResult(ensureResult, currentTarget, mod);
 
       if (decision.action === 'block') {
         console.warn(
@@ -1126,7 +507,7 @@ async function _preflightDeps(fullPath, headers, selected, NU) {
         if (!result.depWarnings) {
           result.depWarnings = new Map();
         }
-        const reviewResult = _handleDepReview({
+        const reviewResult = handleDepReview({
           spmService,
           currentTarget,
           mod,