autosnippet 1.2.15 → 1.2.17

package/.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*.js]
+indent_style = tab
+indent_size = 4
+tab_width = 4
+

package/ARCHITECTURE.md

@@ -0,0 +1,305 @@
+## AutoSnippet 架构与调用流程（实现解析）
+
+本文档用于解释 AutoSnippet 的实现方式、核心调用链、以及每个文件/模块的职责边界。当前版本已统一使用 `autosnippet:*` 指令（不再兼容旧标记）。
+
+---
+
+## 总览：分层结构
+
+AutoSnippet 采用“薄 `bin/` + 业务下沉 `lib/`”的结构：
+
+- **`bin/`（CLI/兼容入口层）**
+  - 只负责 CLI 参数解析、拼装 options、调用 `lib/` 的能力（或 re-export）
+  - 便于保持可执行入口稳定（`package.json` 的 bin 指向不变）
+
+- **`lib/`（可复用能力层）**
+  - `infra/`：路径与缓存
+  - `snippet/`：snippet 构建、spec 读写、写入 Xcode CodeSnippets
+  - `watch/`：watcher + debounce + 事件提取
+  - `injection/`：指令解析、模块推断、写入 import、串联依赖补齐
+  - `spm/`：Package.swift 解析/修复（target/product/package）
+
+- **`scripts/`（测试/辅助）**
+  - 跨目录 E2E：验证全局 asd 在任意 Xcode 项目里可用，并覆盖 SPM 自动补齐
+
+---
+
+## 核心指令（Source Directive）
+
+### snippet 指令：`autosnippet:code`
+
+用于从源码中抽取 snippet 内容：
+
+```txt
+// autosnippet:code
+... snippet content ...
+// autosnippet:code
+```
+
+### 注入指令：`autosnippet:include` / `autosnippet:import`
+
+- ObjC/C/C++：注入 `#import`
+
+```txt
+// autosnippet:include <ModuleName/Header.h> [optional/relative/path/Header.h]
+```
+
+- Swift：注入 `import`
+
+```txt
+// autosnippet:import ModuleName
+```
+
+> 重要：Swift 的 `import ModuleName` 同样需要 **target 依赖**（在 SPM 中就是 `Package.swift` 的 target `dependencies`），因此 Swift 注入路径也会触发依赖补齐（见下文）。
+
+---
+
+## 调用流程 1：创建 snippet（create）
+
+目标：把源码/剪贴板内容生成 snippet，写入 `AutoSnippet.boxspec.json` / `AutoSnippetRoot.boxspec.json`，并安装到 Xcode CodeSnippets。
+
+### 1) CLI 入口
+
+- `bin/asnip.js`
+  - `asd create` / `asd c`
+  - 支持 `--preset` / `--yes`
+  - 支持 `--clipboard` / `--lang objc|swift`
+
+### 2) 从文件标记抽取
+
+- `bin/create.js`
+  - 扫描目录下 `.m/.h/.swift`
+  - 识别 `// autosnippet:code` 开关区间
+- 组装 snippet 对象（identifier/trigger/summary/link/languageShort/body）
+  - 交给 `lib/snippet/specRepository.js` 落盘并触发 install
+
+### 3) 从剪贴板创建（clipboard）
+
+- `bin/asnip.js` 读取剪贴板文本（平台命令）
+- `bin/create.js` → `lib/snippet/snippetFactory.js`
+  - `snippetFactory.fromText(answers, text, { language })`
+
+### 4) 落盘与安装
+
+- `lib/snippet/specRepository.js`
+  - `readSpecFile` / `writeSpecFile`
+  - `saveSnippet(specFile, snippet, { syncRoot, installSingle })`
+  - 同步根配置（root spec）与更新缓存
+
+- `lib/snippet/snippetInstaller.js`
+  - `addCodeSnippets(specFile)`
+  - 写入 `~/Library/Developer/Xcode/UserData/CodeSnippets/*.codesnippet`
+
+---
+
+## 调用流程 2：watch 注入（watch）
+
+目标：监听文件变更，识别 `autosnippet:include/import` 或 `@xxx#alink`，然后执行注入/跳转。
+
+### 1) CLI 入口
+
+- `bin/asnip.js`
+  - `asd watch` / `asd w`
+  - 过滤选项：`--path/--file/--ext`
+  - 输出选项：`--quiet/--summary`
+  - 测试选项：`--duration/--once`
+  - 在启动 watch 前会先 `init.mergeSubSpecs(rootSpecFile)`，保证 root spec 结构可用
+
+### 2) 文件监听与事件提取
+
+- `lib/watch/fileWatcher.js`
+  - `watchFileChange(rootSpecFile, projectRoot, options)`
+  - 基于 `chokidar` 监听 `m/h/swift`（或指定 exts）
+  - 读取文件内容后：
+    - 收集当前已有 `#import` / `import` 列表（用于“已存在则不重复插入”）
+    - 检测是否存在 `// autosnippet:include ...` 或 `// autosnippet:import ...`
+    - 检测是否存在 `@xxx#alink`
+  - 命中后触发：
+    - header：`checkAnotherFile(...)` → `injection.handleHeaderLine(...)`
+    - alink：`openLink(...)`
+
+> `checkAnotherFile`：当变更文件是 `.m`，会优先对同名 `.h` 做注入（保持 ObjC 的头文件习惯）。
+
+### 3) 注入编排（ObjC/Swift 共用入口）
+
+- `bin/injection.js`
+  - 薄入口：re-export 到 `lib/injection/injectionService.js`
+
+- `lib/injection/injectionService.js`
+  - 主入口：`handleHeaderLine(specFile, updateFile, headerLine, importArray, isSwift)`
+  - 串联以下步骤（ObjC/Swift 路径略有差异）：
+    - 解析指令
+    - 推断当前 target/module
+    - **（跨 module 时）调用 `deps.ensureDependency()` 补齐 SPM 依赖**
+    - 写入 `#import` / `import` 并移除指令行
+
+---
+
+## 调用流程 3：SPM 依赖自动补齐（deps.ensureDependency）
+
+目标：当发现 `fromTarget -> toTarget` 缺失依赖时，按模式：
+- `off`：只提示
+- `suggest`：给出可复制的 patch 建议
+- `fix`：直接修改 `Package.swift`
+
+入口来源：
+- ObjC 注入：解析出 header 的 moduleName 后触发补齐
+- Swift 注入：`import ModuleName` 的 moduleName 即依赖目标，同样触发补齐
+
+### 1) 入口与模式
+
+- `bin/deps.js`
+  - 薄入口：re-export 到 `lib/spm/spmDepsService.js`
+
+- `lib/spm/spmDepsService.js`
+  - `getFixMode()`：读取 `ASD_FIX_SPM_DEPS_MODE`
+  - `ensureDependency(specFile, packageSwiftPath, fromTarget, toTarget)`
+    - 先判断是否已可达 / 已存在依赖
+    - 若缺失：
+      - 同包 target → 补齐 target dependencies（`.target` / `.byName` 或 `"B"` 等）
+      - 跨包 product → 补齐 `.product(name:package:)`
+      - 若映射里包含 packageRef → 补齐顶层 `.package(...)`（`dependencies:` 参数）
+
+### 2) Package.swift 修改策略（AST-lite）
+
+核心策略是“**轻量解析 + 结构化 patch**”，避免靠简单正则误插入：
+
+- 抽取 `Package(...)` 的 `targets` 列表 block
+- 精确定位某个 target 的 `.target(...)` block
+- 在该 block 的 `dependencies:` 中插入 `.product(...)` / `.target(...)` 或字符串依赖
+- 若需要 `.package(...)`，精确定位 `Package(...)` 的顶层 `dependencies:` 参数
+  - 如果不存在 `dependencies:` 参数，则在 `targets:` 参数之前插入
+
+### 3) 跨包映射文件：`AutoSnippet.spmmap.json`
+
+当 `toTarget` 属于外部包时，需要映射告诉工具：
+- `toModule` 对应哪个 product
+- product 属于哪个 package
+- package 的引用方式（url/path）
+
+该文件用于避免“猜测式补齐”，保证补齐是可解释、可复现的。
+
+---
+
+## ALink 跳转（@xxx#alink）
+
+- `lib/watch/fileWatcher.js`
+  - 捕获 `@xxx#alink` 行
+  - `openLink(...)`：打开 link 或 README（具体链接来源来自 spec）
+
+---
+
+## 各文件职责（按目录）
+
+### bin/
+
+- `bin/asnip.js`
+  - CLI 主入口（commander）
+  - 负责：命令定义、参数解析、preset/yes 统一、调用下层服务
+
+- `bin/init.js`
+  - 初始化 spec、合并子 spec 到 root spec（watch 启动前依赖它做“根配置兜底”）
+
+- `bin/create.js`
+  - 从 `autosnippet:code` 抽取 snippet（文件模式）
+  - clipboard 模式下调用 `lib/snippet/snippetFactory.js`
+
+- `bin/install.js`
+  - 薄入口：re-export `lib/snippet/snippetInstaller.js`
+
+- `bin/share.js`
+  - 读取本地 Xcode CodeSnippets 并写入 spec（委托 `specRepository`）
+
+（已移除薄入口）`watch/injection/deps/install/cache/config` 等能力已直接从 `lib/` 引用，`bin/` 保持只承载 CLI 与命令实现。
+
+- `bin/findPath.js`
+  - 工程路径/Package.swift 定位与解析辅助（后续可继续下沉到 `lib/spm/`）
+
+（已移除薄入口）路径与缓存能力：`lib/infra/paths.js`、`lib/infra/cacheStore.js`
+
+### lib/infra/
+
+- `lib/infra/paths.js`
+  - `getSnippetsPath()` / `getCachePath()`
+
+- `lib/infra/cacheStore.js`
+  - 缓存读写（keys/link/head 等）
+  - 提供 watch/injection/create 中所需的缓存支持
+
+### lib/snippet/
+
+- `lib/snippet/snippetFactory.js`
+  - snippet 组装（目前以 `fromText` 为主）
+
+- `lib/snippet/specRepository.js`
+  - spec 文件读写、upsert、同步 root、更新缓存
+
+- `lib/snippet/snippetInstaller.js`
+  - 渲染/写入 `.codesnippet` 到 Xcode 目录
+
+### lib/watch/
+
+- `lib/watch/fileWatcher.js`
+  - chokidar + 过滤 + debounce + summary
+  - 解析事件并调用 injection/openLink
+
+### lib/injection/
+
+- `lib/injection/directiveParser.js`
+  - 解析 `autosnippet:include/import`
+  - ObjC include 解析为 `{moduleName, headerName, headRelativePathFromMark}` 等结构
+
+- `lib/injection/moduleResolver.js`
+  - 根据 `Package.swift` 的 targets 以及路径推断当前 target/module
+  - 根据 headRelativePath 推断头文件所属 module（ObjC 路径使用）
+
+- `lib/injection/importWriter.js`
+  - 负责写入 `#import` / `import`、移除指令行、提示通知
+  - 负责判断“已存在则不重复”
+
+- `lib/injection/injectionService.js`
+  - orchestration：解析 → 推断 → deps.ensureDependency → 写入
+  - Swift/ObjC 保持“功能一致”，实现方式不同（Swift 无头文件路径）
+
+### lib/spm/
+
+- `lib/spm/spmDepsService.js`
+  - 依赖图构建与缓存（DepGraphCache）
+  - manifest/targets 解析、reachability 判断
+  - patch：target dependency / product dependency / package dependency
+  - 统一输出 `ensureResult`（ok/changed/changes/suggestion/reason）
+
+### scripts/
+
+- `scripts/test-cross-directory.js`
+  - 跨目录 E2E（验证全局 asd 在任意项目可用）
+  - 覆盖：
+    - init/root/create/install/update/share/watch
+    - SPM 同包 target 依赖补齐
+    - Swift import 依赖补齐
+    - 跨包 product/.package 依赖补齐
+    - 真实项目抽样修复（并清理痕迹）
+
+---
+
+## 常见“为什么这样设计”
+
+### 为什么 `bin/` 要薄
+
+- CLI 稳定，内部可重构
+- 单元测试/E2E 更容易直接调用 `lib/` 能力
+- 避免循环依赖（create/install/share/watch/deps 等互相引用）
+
+### 为什么 SPM 解析不用完整 AST
+
+- `Package.swift` 是 Swift 代码，完整 AST 解析成本高
+- 采用“AST-lite”定位结构区域并 patch，结合 E2E fixture 保证可靠性
+
+---
+
+## 扩展建议（后续演进）
+
+- ✅ 已完成：把 `Package.swift` 解析/定位能力抽到 `lib/spm/packageParser.js`，`lib/spm` 与 `lib/injection` 不再依赖 `bin/findPath.js`
+- ✅ 已完成（通知层）：新增 `lib/infra/notifier.js`，统一 macOS `osascript` 通知并修复换行/引号导致的脚本错误
+- 🔜 待完善（日志层）：统一日志层（quiet/json），把散落的 `console.*` 收敛到一个可配置 logger（CLI 透传 quiet/json）
+

package/README.md

@@ -1,6 +1,6 @@
 # AutoSnippet
 
-基于SPM的iOS模块管理工具。通过AutoSnippet可以将模块的使用示范写进Xcode的配置文件，支持分类查询和头文件引入。
+基于 SPM 的 iOS 模块 Snippet 工具。通过 AutoSnippet 可以把模块的使用示范写进 Xcode 的 CodeSnippets，并支持分类检索、链接跳转与（可选）依赖头文件注入。
 
 [![npm version](https://img.shields.io/npm/v/autosnippet.svg?style=flat-square)](https://www.npmjs.com/package/autosnippet)
 [![npm downloads](https://img.shields.io/npm/dm/autosnippet.svg?style=flat-square)](https://www.npmjs.com/package/autosnippet)
@@ -29,7 +29,34 @@ Toast模块添加配置时可以选择分类，使用者可以通过`@view`或
 $ npm install -g autosnippet
 ```
 
-## 命令选项
+## 快速开始
+
+建议在**项目根目录**执行（能找到 `AutoSnippetRoot.boxspec.json`）。
+
+```bash
+# 1) 一键初始化（等价于 init + root）
+asd setup
+
+# 2) 在代码里用新标记圈出 snippet 内容，然后创建
+asd create
+
+# 3) 安装到 Xcode CodeSnippets
+asd install
+
+# 4) 开启监听（用于头文件注入/依赖补齐/ALink 跳转）
+asd watch
+```
+
+## 全局选项（推荐）
+
+- **`--preset <path>`**：指定预置输入（非交互/自动化最常用）。
+- **`--yes`**：非交互模式；缺少必要输入会直接报错退出。
+
+也支持环境变量（方便 CI / 测试脚本）：
+
+- **`ASD_PRESET` / `ASD_TEST_PRESET`**：预置输入 json 路径（优先级低于 `--preset`）
+
+## 命令
 
 请在当前 Xcode 项目文件目录下使用以下所有命令。
 
@@ -51,20 +78,47 @@ $ asd root
 $ asd init
 ```
 
+### setup（推荐）
+
+初始化快捷命令，等价于 `asd init` + `asd root`：
+
+```bash
+$ asd setup
+```
+
 ### create
 
-创建 Xcode 代码片段的命令，在标记有 `// ACode` 代码的文件目录中：
+创建 Xcode 代码片段（支持从文件标记提取，或直接从剪贴板生成）。
 
 ```bash
+$ asd create
+# 或短别名
 $ asd c
 ```
 
-代码示例：
+#### 从文件标记提取
+
+在任意 `.m/.h/.swift` 文件中使用标记圈出代码块（推荐短写法）：
 
 ```
-// ACode
+// as:code
 UIView *view = [[UIView alloc] init];
-// ACode
+// as:code
+```
+
+然后在该文件所在目录（或通过 preset 指定文件）执行 `asd create`。
+
+#### 从剪贴板创建
+
+```bash
+# 默认按 objc 处理
+asd create --clipboard
+
+# 短写法
+asd c -p
+
+# Swift
+asd create --clipboard --lang swift
 ```
 
 ### install
@@ -72,6 +126,8 @@ UIView *view = [[UIView alloc] init];
 将共享的代码片段添加到 Xcode 环境：
 
 ```bash
+$ asd install
+# 或短别名
 $ asd i
 ```
 
@@ -87,17 +143,45 @@ $ asd i
 共享本地代码片段：
 
 ```bash
+$ asd share
+# 或短别名
 $ asd s
 ```
 
+### update
+
+更新已创建的 snippet（按 trigger 查找，例如 `cover` 或 `@cover`）：
+
+```bash
+asd update <word> [key] [value]
+# 或短别名
+asd u <word> [key] [value]
+```
+
 ### watch
 
-在模块化项目中，识别代码片段并自动注入依赖头文件：
+在模块化项目中监听文件变更，识别 `autosnippet:*` 指令并执行：
+- 头文件注入（ObjC `#import` / Swift `import`）
+- ALink 跳转
+-（可选）SPM 依赖自动补齐（见下文）
 
 ```bash
+$ asd watch
+# 或短别名
 $ asd w
 ```
 
+常用参数：
+
+```bash
+# 只监听某个子目录/文件/后缀
+asd watch --path Services/Services/ASNetworkCheck --ext m,h
+asd watch --file ./Services/Services/ASNetworkCheck/Code/ASSimplePing.m
+
+# 降噪/退出时打印汇总
+asd watch --quiet --summary
+```
+
 #### 追加头文件
 
 开启监听后，如果想要追加头文件，请执行以下操作：
@@ -108,6 +192,20 @@ $ asd w
 
 在 1 秒内，头文件会自动添加到文件头部。
 
+#### 新指令格式（重要）
+
+- ObjC / C / C++：注入头文件
+
+```
+// as:include <ModuleName/Header.h> [optional/relative/path/Header.h]
+```
+
+- Swift：注入 import
+
+```
+// as:import ModuleName
+```
+
 #### 浏览器查看
 
 开启监听后，如果想要在浏览器中查看模块的更多信息，请执行以下操作：
@@ -124,6 +222,18 @@ $ asd w
 @view#ALink
 ```
 
+## SPM 依赖自动补齐（可选）
+
+当 `watch` 触发跨 target 引用时，AutoSnippet 可以（按配置）检查/补齐 `Package.swift` 里的依赖关系（target / product / package）。
+
+- 开关：通过环境变量控制
+  - **`ASD_FIX_SPM_DEPS_MODE=off`**：只提示（默认行为）
+  - **`ASD_FIX_SPM_DEPS_MODE=suggest`**：输出可复制的补丁建议
+  - **`ASD_FIX_SPM_DEPS_MODE=fix`**：直接修改 `Package.swift` 自动补齐
+
+- 跨包 product/package 依赖需要映射文件（项目内维护）：
+  - `AutoSnippet.spmmap.json`
+
 ## 其他
 
 ### 占位符快捷键