@iyowei/sweep-node-modules 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,48 @@
1
+ import { type PathStyle } from './guard.js';
2
+ export type TargetKind = 'project' | 'suspect-install-tree';
3
+ export interface Classification {
4
+ kind: TargetKind;
5
+ /** kind 为 suspect-install-tree 时的理由 (人话短语, 供清单行尾标注); project 时缺省 */
6
+ reason?: string;
7
+ }
8
+ /**
9
+ * 判定选项: 路径风味与家目录均可注入 (与 guard 的 ValidateOptions 同款),
10
+ * 生产默认取当前平台与 os.homedir(), 测试可在任意宿主上跑平台矩阵。
11
+ */
12
+ export interface ClassifyOptions {
13
+ /** 路径风味 (分隔符与大小写敏感性); 缺省平台原生 */
14
+ style?: PathStyle;
15
+ /** 家目录 (判定「位于家目录下的隐藏目录」用); 缺省 os.homedir(), 显式传 null 关闭该判定 */
16
+ home?: string | null;
17
+ }
18
+ /**
19
+ * 判定目标类别。
20
+ *
21
+ * 判定顺序 (逐条短路, 证据强度递减):
22
+ * 1. `node_modules` 之上任一级目录名命中安装树容器名 → 安装树
23
+ * (容器名是工具私有约定, 指认最具体: `~/.nvm/.../lib/node_modules` 报的是 `.nvm` 而非泛化的 lib);
24
+ * 2. `node_modules` 的父目录名为 `lib` → 安装树形态
25
+ * (fnm / nvm / volta / asdf 的全局包一律落在 `<版本目录>/lib/node_modules`, 管理器的根不在
26
+ * 默认名单里时由本形态兜住);
27
+ * 3. `node_modules` 落在**家目录下的隐藏目录**里 → 安装树形态
28
+ * (隐藏目录是应用私有数据的惯例落点: 实测命中 `~/.oh-my-opencode` 237 MB、`~/.stepfun/releases/deps-6`
29
+ * 51 MB、`~/.jcode/skills/archify` 等未收录进默认名单的应用根; 用户项目极少藏进点目录, 而这批
30
+ * 应用的安装树形态各异、名字无法穷举, 故按形态兜);
31
+ * 4. 其余 → 用户项目依赖。
32
+ *
33
+ * ### 数据追踪示例
34
+ * ```text
35
+ * Input(真实 Payload)
36
+ * target = '/Users/iyowei/.bun/install/global/node_modules'
37
+ *
38
+ * 步骤 1:切段并去掉末段 (node_modules 自身不构成路径上的一级)
39
+ * ancestors = ['Users', 'iyowei', '.bun', 'install', 'global']
40
+ *
41
+ * 步骤 2:逐级判容器名 ('.bun' 命中安装树容器名)
42
+ * kind = 'suspect-install-tree', reason = '位于 .bun 安装树目录'
43
+ *
44
+ * Output(数据契约)
45
+ * return { kind: 'suspect-install-tree', reason: '位于 .bun 安装树目录' }
46
+ * ```
47
+ */
48
+ export declare function classifyTarget(target: string, options?: ClassifyOptions): Classification;
@@ -0,0 +1,41 @@
1
+ /**
2
+ * 判别值与枚举的类型集: 错误码 / 告警码 / 跳过原因 / 体积口径 / 编排阶段。
3
+ *
4
+ * 契约基准: docs/designs/api-surface.md §3.2 与 §7.3。
5
+ * 命名规则: `<域>_<判定>`, 全大写蛇形; 域取自模块 (SCAN / SIZE / GUARD / REMOVE / CONFIG / SWEEP)。
6
+ * 硬纪律: **code 一经发布即冻结, 只增不改** (废弃走文档标注, 不回收取值);
7
+ * 且同一个 code 不得合并「处置方向相反」的语义 (调用方必须能不读 message 就决定下一步)。
8
+ */
9
+ /** 扫描段告警码 (进 ScanResult.warnings) */
10
+ export type ScanWarningCode = 'SCAN_ROOT_MISSING' | 'SCAN_ROOT_UNREADABLE' | 'SCAN_ROOT_NOT_DIR' | 'SCAN_ROOT_UNAVAILABLE' | 'SCAN_DIR_UNREADABLE';
11
+ /** 体积段告警码 (进 SizeResult.warnings, 只作事件、不作划分) */
12
+ export type SizeWarningCode = 'SIZE_DU_OUTPUT_MISMATCH' | 'SIZE_DU_LINE_UNATTRIBUTED' | 'SIZE_SUBPATH_FAILED' | 'SIZE_TARGET_VANISHED' | 'SIZE_DU_UNAVAILABLE';
13
+ /** 并集别名: 后续新增告警域时随之扩展 */
14
+ export type SweepWarningCode = ScanWarningCode | SizeWarningCode;
15
+ /** 未测到原因码 (进 SizeResult.unmeasured[].code) */
16
+ export type UnmeasuredCode = 'SIZE_UNMEASURED_PERMISSION' | 'SIZE_UNMEASURED_NOT_DIR' | 'SIZE_UNMEASURED_LOOP' | 'SIZE_UNMEASURED_UNPARSEABLE' | 'SIZE_UNMEASURED_CONTROL_CHAR' | 'SIZE_UNMEASURED_OTHER';
17
+ /**
18
+ * 安全闸拒绝码 (逐条对应 validateTargets 分支)。
19
+ * realpath 失败按 errno 三分: MISSING 是唯一可被 staleTargets: 'missing' 容忍的一类
20
+ * (目标已达成); 另两类必须维持整批拒绝。
21
+ */
22
+ export type GuardCode = 'GUARD_LEAF_NOT_NODE_MODULES' | 'GUARD_TARGET_MISSING' | 'GUARD_TARGET_UNREADABLE' | 'GUARD_REALPATH_FAILED' | 'GUARD_ROOT_ANCHOR_SYMLINK' | 'GUARD_FILESYSTEM_ROOT_BODY' | 'GUARD_HOME_BODY' | 'GUARD_REAL_LEAF_NOT_NODE_MODULES' | 'GUARD_OUTSIDE_ROOTS' | 'GUARD_DUPLICATE_TARGET';
23
+ /** 删除失败码 (含复核未完成的非失败条目) */
24
+ export type RemoveFailureCode = 'REMOVE_FAILED' | 'REMOVE_ENOENT_SURVIVOR' | 'REVIEW_UNVERIFIED' | 'REVIEW_COMPONENT_VANISHED';
25
+ /** 整批中止码 (复核阶段的致命信号) */
26
+ export type AbortCode = 'REVIEW_NOT_UNDER_ANY_ROOT' | 'REVIEW_HEAD_SYMLINK' | 'REVIEW_COMPONENT_REPLACED';
27
+ /** 库抛出的错误码 (配置 / 参数 / 取消三档共用, 见 errors.ts 的 SweepError) */
28
+ export type SweepErrorCode = 'CONFIG_READ_FAILED' | 'CONFIG_CORRUPT_JSON' | 'CONFIG_CORRUPT_SHAPE' | 'CONFIG_ABSENT' | 'INVALID_ARGUMENT' | 'CANCELLED';
29
+ /**
30
+ * 跳过原因 (与 classify.ts / guard.ts 的既有判定同源)。
31
+ * 与 stale 的分界: 体积测不到是「存在但测不出」, 进不了批;
32
+ * 目标已不存在是「没有东西可测」, 走 gone 桶与 staleTargets 策略, 二者不混。
33
+ */
34
+ export type SkipReason = 'suspect-install-tree' | 'cross-device:on-path' | 'cross-device:target-itself' | 'unmeasured';
35
+ /**
36
+ * 体积口径标识: du 快路径报磁盘占用, 纯实现报逻辑字节。
37
+ * 一次 measure() 调用内口径恒一; win32 恒为 logical-bytes (EC-03 的平台守卫)。
38
+ */
39
+ export type SizeBasis = 'disk-usage' | 'logical-bytes';
40
+ /** 编排阶段 (取消错误的 details.phase 取本全集) */
41
+ export type SweepPhase = 'scan' | 'measure' | 'classify' | 'device' | 'plan' | 'validate' | 'remove';
@@ -0,0 +1,115 @@
1
+ export interface Config {
2
+ /** 扫描根, 任意多个 */
3
+ roots: string[];
4
+ /** 排除名单: 从根到命中点的任意一级目录名命中即跳过; 配置文件省略该字段时取 DEFAULT_EXCLUDE */
5
+ exclude: string[];
6
+ /** 包含名单 (白名单): 从根到 node_modules 的任意一级目录名命中才纳入; 空数组 = 不过滤 */
7
+ include: string[];
8
+ }
9
+ /**
10
+ * 默认排除名单 (保守基线): 已知的包管理器 / 版本管理器安装树、编辑器扩展目录与系统 / 应用数据根。
11
+ * 这些目录下的 node_modules 是工具自身的安装树 (全局包树、npx 缓存、扩展依赖), 删除后无法由
12
+ * 项目级重装恢复 — 安全审计确证 ADR 0002 的「可恢复, 非数据损失」前提在此类目标上不成立
13
+ * (实测: `~/.bun/install/global` 4.25 GB / 1627 包, 且本工具自身即装于其中; 版本管理器的
14
+ * `lib/node_modules` 是用户全局包清单的唯一所在; 编辑器扩展目录逐个自带 node_modules)。
15
+ *
16
+ * 语义与用户写的名单完全一致 (任意一级目录名命中即跳过), 只是默认值不再为空; 生效与覆盖规则:
17
+ * - 配置文件省略 `exclude` 字段时取本名单; 显式写出该字段 (含写空数组) 即以用户名单为准;
18
+ * - `init` 向导的排除一问以本名单为默认回填, 用户所见即所得;
19
+ * - 名单项在本次扫描零命中时不告警 (静默规则见 cli.ts 的 collectNameNotes): 名单依平台与用户
20
+ * 环境而异, 逐项告警必然刷屏且无行动价值, 与用户手写名字拼错的情况不同。
21
+ *
22
+ * 保守取向: 宁可挡住个别同名的真实项目 (用户可从配置中删除该项), 也不漏放安装树。
23
+ */
24
+ export declare const DEFAULT_EXCLUDE: readonly string[];
25
+ /** 配置路径来源 */
26
+ export type ConfigSource = 'flag' | 'env' | 'platform-default';
27
+ /** 环境变量表 (注入; 生产默认 process.env) */
28
+ export type EnvTable = Record<string, string | undefined>;
29
+ export interface ResolveConfigPathOptions {
30
+ /** `--config` 旗标值, 最高优先级 */
31
+ flag?: string;
32
+ /** 平台标识, 默认 process.platform; 测试注入 'win32' 等 */
33
+ platform?: string;
34
+ /** 家目录, 默认 os.homedir() */
35
+ homedir?: string;
36
+ /** 环境变量表, 默认 process.env; 承载 SWEEP_NM_CONFIG 与 win32 的 APPDATA / USERPROFILE */
37
+ env?: EnvTable;
38
+ }
39
+ export interface ResolvedConfigPath {
40
+ /** 配置文件路径 (旗标 / 环境变量值原样透传, 平台默认按目标平台拼装) */
41
+ path: string;
42
+ /** 命中来源, 供调用方日志与分流 */
43
+ source: ConfigSource;
44
+ }
45
+ export type LoadConfigResult = {
46
+ state: 'ok';
47
+ config: Config;
48
+ } | {
49
+ state: 'absent';
50
+ };
51
+ /**
52
+ * 解析配置路径: 按 `--config` 旗标 > 环境变量 SWEEP_NM_CONFIG > 平台默认 的顺序取首个可用来源。
53
+ *
54
+ * ### 数据追踪示例
55
+ * ```text
56
+ * Input(真实 Payload)
57
+ * options = { flag: undefined, env: { SWEEP_NM_CONFIG: '/env/config.json' }, platform: 'win32', homedir: 'C:\\Users\\u' }
58
+ *
59
+ * 步骤 1:旗标缺失, 环境变量命中
60
+ * path = '/env/config.json'
61
+ * source = 'env'
62
+ *
63
+ * Output(数据契约)
64
+ * return { path: '/env/config.json', source: 'env' }
65
+ * ```
66
+ */
67
+ export declare function resolveConfigPath(options: ResolveConfigPathOptions): ResolvedConfigPath;
68
+ /**
69
+ * 装载配置: 文件缺失是正常状态 (absent), 供 init 向导分流, 不作为错误;
70
+ * 损坏 (JSON 解析失败 / 形状不符) 与读取失败一律抛 SweepError (CONFIG_* 码与 details, 见 §3.6)。
71
+ *
72
+ * ### 数据追踪示例
73
+ * ```text
74
+ * Input(真实 Payload)
75
+ * path = '/Users/iyowei/.config/sweep-node-modules/config.json'
76
+ *
77
+ * 步骤 1:读文件
78
+ * text = '{"roots":["/a"],"exclude":["x"]}'
79
+ * *(ENOENT 时提前返回 { state: 'absent' }, 其余读取失败立即抛错)*
80
+ *
81
+ * 步骤 2:JSON 解析 + 形状校验 (roots 须为字符串数组; 字段缺省时 exclude 补默认名单、include 补 [])
82
+ * data = { roots: ['/a'], exclude: ['x'] }
83
+ *
84
+ * Output(数据契约)
85
+ * return { state: 'ok', config: { roots: ['/a'], exclude: ['x'], include: [] } }
86
+ * ```
87
+ */
88
+ export declare function loadConfig(path: string): Promise<LoadConfigResult>;
89
+ /**
90
+ * 装载已解析路径的配置: 显式来源 (--config 旗标 / SWEEP_NM_CONFIG) 指向的文件不存在时抛错,
91
+ * 防打错的路径被静默降级为「配置缺失」而回退扫 cwd (配 --yes 会删错地方);
92
+ * 平台默认来源保留软行为, absent 交上层走向导 / cwd 回退。
93
+ * 须在 scan 之前调用, 保证显式路径写错时不进入扫描与删除。
94
+ */
95
+ export declare function loadResolvedConfig(resolved: ResolvedConfigPath): Promise<LoadConfigResult>;
96
+ /**
97
+ * 合并名单 (排除与包含共用): 配置名单在前、命令行追加在后, 跨来源去重 (保留首见顺序);
98
+ * 同时静默剔除两个写进名单也永不生效的名字, 两者理由不同:
99
+ * - node_modules: 本工具唯一的目标, 写进两份名单里都不成立。列入排除名单等于排掉唯一操作目标
100
+ * (工具彻底失效); 列入包含名单则是永久零命中 (扫描读到 node_modules 即剪枝, 该名字只可能落在
101
+ * 候选路径的末段, 而名单判定只看中间级别, 见 scan-native.ts 中 Candidate.segments 的
102
+ * 「末段恒为 node_modules」)。
103
+ * - .git: 扫描恒定跳过的目录 (三名候选均不产出其下的命中: prune / parallel 在进入目录时短路,
104
+ * native 在后过滤里剔除含 .git 路径段的候选), 从不参与名单判定。留在名单里只会换来一条结构性
105
+ * 假告警: 该目录客观存在, 却因剪枝早于逐名计数而被报成「未命中任何已扫描的目录」, 恰是这条反馈通道
106
+ * 最该避免的误导。
107
+ *
108
+ * 剔除只做静默丢弃, 不报错、不阻断、不告警; 匹配口径与其余名单判定一致, 按名精确匹配且区分大小写。
109
+ * 内含 include 侧的一个易误解点: 剔空后等于「不过滤」(空数组即不过滤, 见 Config.include),
110
+ * 而不是「只扫 node_modules」。
111
+ *
112
+ * 落点选在合并收口处而非逐个扫描候选改判定: 所有消费方都经此处取名单, 三名候选
113
+ * (prune / parallel / native) 天然不含这两个名字, 一处收口胜过三处判定修改。
114
+ */
115
+ export declare function mergeNames(configNames: string[], cliNames: string[]): string[];
@@ -0,0 +1,155 @@
1
+ import type { AbortCode, RemoveFailureCode } from './codes.js';
2
+ import { type PathMapping, type PathStyle, type RejectedTarget } from './guard.js';
3
+ export interface TargetFailure {
4
+ /** 调用方传入的目标 (原样回显, 不做二次 realpath) */
5
+ target: string;
6
+ /** 机器可判别的失败码 (程序分流只许看它, 严禁对 message 做字符串匹配) */
7
+ code: RemoveFailureCode;
8
+ /** 原始 errno (EACCES / EBUSY / ENOENT …), 无则缺省 */
9
+ errno?: string;
10
+ /**
11
+ * 「错误码: 人话 (目标: 路径; …)」形态的可读串 (文案逐字保留现状)。
12
+ * 删除已尝试而失败时附复查提示 (内容可能已残缺); 复核未通过而根本未删则注明「未执行删除」。
13
+ */
14
+ message: string;
15
+ /** 内容可能已被部分或全部删除 (EC-05 半完成语义的机器标记); false 意味着「未执行删除」 */
16
+ partialRisk: boolean;
17
+ }
18
+ /** 整批中止信息 (首个复核未通过的目标) */
19
+ export interface AbortedBatch {
20
+ /** 触发中止的目标 (未被删除) */
21
+ target: string;
22
+ /** 机器可判别的中止码 */
23
+ code: AbortCode;
24
+ /** 中文人话, 含定位 (文案逐字保留现状) */
25
+ message: string;
26
+ /** 定位路径 (触发中止的根 / 组件) */
27
+ path?: string;
28
+ }
29
+ export interface RemovalResult {
30
+ /** 实际删除成功的目标 (保输入顺序) */
31
+ removed: string[];
32
+ /** rm 报 ENOENT 且复核确认目标本体已不存在的目标; 目标已达成, 计成功侧 (保输入顺序) */
33
+ missing: string[];
34
+ /** 删除失败与复核未完成 (组件消失 / 不可核验) 的目标及原因 (保输入顺序); 后者未执行删除 */
35
+ failed: TargetFailure[];
36
+ /** 安全复核未通过即中止整批, 其间条目一律不删; 未触发时缺省 */
37
+ aborted?: AbortedBatch;
38
+ }
39
+ /** 删除操作的进度事件 (每条目标出桶即发一条) */
40
+ export type RemovalProgressEvent = {
41
+ kind: 'removed';
42
+ target: string;
43
+ } | {
44
+ kind: 'missing';
45
+ target: string;
46
+ } | {
47
+ kind: 'failed';
48
+ failure: TargetFailure;
49
+ } | {
50
+ kind: 'aborted';
51
+ aborted: AbortedBatch;
52
+ };
53
+ /**
54
+ * 信任根: 配置里的原始拼写与 realpath 归一形态成对出现 (配对由类型强制, 拆开即失去一层防线)。
55
+ * - `configured`: 链头判定的对象 —— 配置里的名字被换成符号链接时, 只有拼写形态能检出;
56
+ * - `real`: isUnder 与复核链的比较基准, 须与 targets 同源 (realpath 形态; 根不可解析时调用方保留原拼写)。
57
+ */
58
+ export interface TrustRoot {
59
+ configured: string;
60
+ real: string;
61
+ }
62
+ export interface RemovalOptions {
63
+ /**
64
+ * 可删目标所属的信任根 (与 guard 同源)。`real` 拼写须与 targets 一致 (建议同为 realpath 化结果);
65
+ * `configured` 供链头判定。目标不在任何根之下时无可信复核, 整批中止。
66
+ */
67
+ roots: TrustRoot[];
68
+ /** 取消信号; 只在条目之间检查, 绝不在单条 rm 中途中断 (那会制造新的半删状态) */
69
+ signal?: AbortSignal;
70
+ /** 进度回调; 粒度: 每条目标出桶即发一条 */
71
+ onProgress?: (event: RemovalProgressEvent) => void;
72
+ }
73
+ /**
74
+ * 逐条复核并删除目标, 失败不中断整批, 复核不通过则整批中止, 按结果分桶
75
+ * (removed / missing / failed 均保输入顺序)。
76
+ *
77
+ * 并发模型 (为什么可并发、以及安全模型为何不变, 三条论证):
78
+ * ① rm 不可中断的纪律与「复核紧跟删除」的条内时序逐字保留 (并发收益不来自砍复核 —— 复核
79
+ * 实测仅占 3%), 单条 rm 仍绝不在中途中断;
80
+ * ② 目标间不嵌套 (扫描对 node_modules 命中即剪枝), 任一目标的复核链 (root → 父目录) 不可能
81
+ * 落在别条目标的删除面上, 故并发 rm 不会污染彼此的复核读;
82
+ * ③ 中止 / 取消定义为「停止派发新条 + 在飞条目跑完」: aborted 取**批次序最前**的触发条
83
+ * (多条并发检出时按索引比较, 与串行「首个触发条」一致, 不随调度漂动);
84
+ * 取消时 partial = 全部已派发条目的桶 (派发序确定, 已派发集合是批次的连续前缀; 前缀长度
85
+ * 随调度水位, 仅影响中止 / 取消快照的粒度, 不影响任何安全判定)。
86
+ * 桶恒按输入顺序输出 (收集后按批次索引重排, 与并发完成序无关); 进度事件为完成序
87
+ * (事件顺序本不承诺, 见 §4.4)。
88
+ *
89
+ * 数据追踪示例:
90
+ * Input targets = ['/w/zeta/node_modules', '/w/lock/node_modules', '/w/bare/node_modules'],
91
+ * options.roots = [{ configured: '/w', real: '/w' }] (三者父链均为真目录)
92
+ * 步骤 0 逐条复核: 先判链头 (配置拼写 /w 非符号链接), 再自 /w 向下 lstat 至目标父目录;
93
+ * 链头或组件检出符号链接即整批中止 (停止派发, 在飞跑完), 链上组件 ENOENT 归 failed
94
+ * 步骤 1 首项 rm 成功 → removed
95
+ * 步骤 2 次项 rm 抛 EACCES (父目录只读) → failed, 错误串 'EACCES: 权限不足, 拒绝删除
96
+ * (目标: ...; 注意: 目录内容可能已被部分或全部删除, 请复查)'
97
+ * 步骤 3 末项复核通过, rm 抛 ENOENT 且复核确认目标本体已消失 → missing, 不中断
98
+ * (若复核发现目标本体仍在或不可达, 如 Bun 把内部条目 ENOENT 冒泡为顶层, 则归 failed)
99
+ * Output { removed: ['/w/zeta/node_modules'], missing: ['/w/bare/node_modules'], failed: [...] }
100
+ * (aborted 缺省; 若 /w 被换成指向他树的符号链接, 则中止, 未派发条目不在任何桶)
101
+ */
102
+ export declare function removeTargets(targets: string[], options: RemovalOptions): Promise<RemovalResult>;
103
+ /**
104
+ * 信任根配对助手 (从 CLI 提升, 逻辑逐字不动): 配置拼写 (configured) + realpath 归一 (real) 逐根配对。
105
+ * real 须与 target 同源拼写 (target 已由 guard realpath 化); configured 供删除层的链头判定
106
+ * (根被换成符号链接时只有拼写形态能识破), 故原样透传配置里的拼写, 不做任何归一。
107
+ * realpath 失败的根其 real 保留原拼写 —— 该根下不可能有已通过 guard 的目标, 不会误伤。
108
+ */
109
+ export declare function toTrustRoots(roots: string[]): Promise<TrustRoot[]>;
110
+ /** 写侧编排的调用选项 (配对 + 安全闸 + 整批拒绝 + 陈旧容忍 + 删除收成一个入口) */
111
+ export interface RemoveBatchOptions {
112
+ /** 扫描根 (原始拼写): 安全闸判归属与锚点, 配对助手供给删除侧 */
113
+ roots: string[];
114
+ home?: string | null;
115
+ style?: PathStyle;
116
+ signal?: AbortSignal;
117
+ onProgress?: (event: RemovalProgressEvent) => void;
118
+ /**
119
+ * 安全闸之前「目标已不存在」这一类拒绝如何处置。
120
+ * - 'reject' (缺省, 保现状): 与其余拒绝同款, 触发整批拒绝、零删除 (BC-22);
121
+ * - 'missing': 把这类目标从批次中摘出, 记入 executed 分支的 stale, 不触发整批拒绝,
122
+ * 其余健康目标照删 (沿用 EC-01「目标已达成」的定性); 被摘出的目标不进入删除面。
123
+ * 只对 GUARD_TARGET_MISSING 生效; GUARD_TARGET_UNREADABLE 与其余任何拒绝码
124
+ * 一律维持整批拒绝 (不可读没有任何「已达成」的语义)。
125
+ */
126
+ staleTargets?: 'reject' | 'missing';
127
+ }
128
+ /**
129
+ * 陈旧容忍分拣 (removeBatch 与编排层 sweep.ts 共用, 规则只此一处):
130
+ * staleTargets 为 'missing' 时把 GUARD_TARGET_MISSING 一类无安全信号的拒绝摘出
131
+ * (目标已达成, EC-01 语义), 其余任何拒绝码一律留在 rejected 侧
132
+ * (不可读等拒绝没有任何「已达成」的语义), 维持整批拒绝。两侧均保输入顺序。
133
+ */
134
+ export declare function splitStaleRejections(rejected: RejectedTarget[], staleTargets: 'reject' | 'missing' | undefined): {
135
+ rejected: RejectedTarget[];
136
+ stale: string[];
137
+ };
138
+ /** 整批拒绝与已执行二选一 (BC-22 的判别联合表达) */
139
+ export type BatchOutcome = {
140
+ status: 'rejected';
141
+ rejected: RejectedTarget[];
142
+ } | {
143
+ status: 'executed';
144
+ accepted: string[];
145
+ mappings: PathMapping[];
146
+ /** 因 staleTargets: 'missing' 被摘出的已消失目标 (保输入顺序); 该策略未开启时为空数组 */
147
+ stale: string[];
148
+ removal: RemovalResult;
149
+ };
150
+ /**
151
+ * 写侧编排入口: 配对 + 安全闸 + 整批拒绝 + 陈旧容忍 + 删除收成一个入口,
152
+ * 调用方不必知道 TrustRoot 的存在也能安全删除。
153
+ * 外部副作用:完整删除链 (安全闸只读; 删除按批次执行, 任一硬拒绝即零删除)。
154
+ */
155
+ export declare function removeBatch(targets: string[], options: RemoveBatchOptions): Promise<BatchOutcome>;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * 展示辅助 (纯函数, 零 IO, 无打印): 人类可读体积与输出面净化。
3
+ * 契约基准: docs/designs/api-surface.md §2.6; OF-14 的「唯一实现」义务落此 ——
4
+ * 全输出面 (CLI 清单 / 诊断 stderr / config 报告 / 向导 / 帮助 / 内嵌方) 共用同一实现,
5
+ * 各面一律经此, 严禁另写一份。本模块自 CLI 包 render.ts 上移 (逻辑逐字未动),
6
+ * render.ts 转出转发以保持既有消费方写法不变。
7
+ */
8
+ /**
9
+ * 人类可读体积: 逐级 1024 (B / KB / MB / GB / TB), 保留 1 位小数、整数省略小数尾
10
+ * (对齐示意里的 "4.6 GB" 与 "366 MB" 两种形态); 最小单位 B 取整。
11
+ */
12
+ export declare function formatBytes(bytes: number): string;
13
+ /**
14
+ * 净化行内文本, 全输出面共用的唯一实现 (清单 / 诊断 stderr / config 报告 / 向导 / 帮助的默认配置位置行):
15
+ * 先剥控制类字符 (C0 含 ESC / DEL、C1、bidi 控制含可视觉反转路径的 RLO、零宽与 BOM) ——
16
+ * 既守住非 TTY 零 ANSI 强契约, 也防终端控制序列注入 (改标题 / 清屏 / 光标回写覆盖已打印内容)
17
+ * 与显示名伪造; 制表与换行留给下一步。
18
+ * 再把剩余空白 (含换行) 折成单空格, 使任意输入都压成一行: 既撑不破清单行结构, 也不让一条告警
19
+ * 被换行劈成两行、伪造出一行可信输出 (非 TTY 下 stderr 常被 tee / CI 原样落盘, 日后回放同样生效)。
20
+ * 列宽计算与渲染必须用同一份净化结果, 否则补位错位。
21
+ * 消费方一律经此函数, 严禁各自另写一份 (两份实现必然漂移, 且漂移方向通常是漏剥控制字符)。
22
+ */
23
+ export declare const sanitizeLine: (text: string) => string;
24
+ /**
25
+ * 输出行净化 (保留行首缩进): sanitizeLine 的薄包装, 供逐行写出的诊断与提示面调用。
26
+ * 行首缩进是本工具自带的分级手段 (告警详情行 / 中性提示行压在同组首行之下), 属排版而非外部数据,
27
+ * 不该被净化吞掉; 行内其余位置的空白仍折成单空格, 换行同样折叠。
28
+ */
29
+ export declare const sanitizeOutputLine: (text: string) => string;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * 库抛出的唯一错误类型与判别工具。
3
+ *
4
+ * 契约基准: docs/designs/api-surface.md §3.6。
5
+ * 两条通道的划分 (§3.1): 能列出结果的失败走返回值 (拒绝 / 失败 / 中止 / 未测到 / 跳过);
6
+ * 无法开始或无法继续的失败 (配置 / 参数 / 取消) 才抛 SweepError。
7
+ * 本类是全仓「以 createXxx() 工厂交出实例、不导出类」惯例的唯一例外:
8
+ * 取例外的理由是调用方要 instanceof 判别与 stack 保留 (跨实例场景走 isSweepError)。
9
+ */
10
+ import type { SweepErrorCode, SweepPhase } from './codes.js';
11
+ import type { ConfigSource } from './config.js';
12
+ import type { RemovalResult } from './delete.js';
13
+ /** 抛错附带的上下文: 判别联合, 按 code 取对应一支 */
14
+ export type SweepErrorDetails = {
15
+ path: string;
16
+ errno?: string;
17
+ } | {
18
+ path: string;
19
+ } | {
20
+ path: string;
21
+ field: string;
22
+ } | {
23
+ path: string;
24
+ source: ConfigSource;
25
+ } | {
26
+ field: string;
27
+ } | {
28
+ phase: SweepPhase;
29
+ partial?: RemovalResult;
30
+ };
31
+ /** 库抛出的唯一错误类型 (config / 参数 / 取消三档共用) */
32
+ export declare class SweepError extends Error {
33
+ readonly name: 'SweepError';
34
+ readonly code: SweepErrorCode;
35
+ readonly details?: SweepErrorDetails;
36
+ constructor(code: SweepErrorCode, message: string, details?: SweepErrorDetails);
37
+ }
38
+ /**
39
+ * 类型守卫: 不依赖类身份, 走「Error 形状 + name + code 取值」判别。
40
+ * 扩展 / 打包环境里同一进程可能存在两份库实例, 此时 instanceof SweepError 会假阴;
41
+ * 需要跨实例判别的调用方一律用它。
42
+ */
43
+ export declare function isSweepError(value: unknown): value is SweepError;