@iyowei/sweep-node-modules 0.4.0 → 0.5.1
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.
- package/LICENSE +1 -1
- package/README.md +612 -93
- package/README.zh-CN.md +612 -93
- package/dist/classify.d.ts +48 -0
- package/dist/codes.d.ts +41 -0
- package/dist/config.d.ts +115 -0
- package/dist/delete.d.ts +155 -0
- package/dist/display.d.ts +29 -0
- package/dist/errors.d.ts +43 -0
- package/dist/guard.d.ts +230 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +1780 -0
- package/dist/manifest.json +4 -3
- package/dist/runtime.d.ts +26 -0
- package/dist/scan-native.d.ts +2 -0
- package/dist/scan-parallel.d.ts +2 -0
- package/dist/scan-prune.d.ts +2 -0
- package/dist/scan.d.ts +6 -0
- package/dist/size-du.d.ts +33 -0
- package/dist/size-js.d.ts +2 -0
- package/dist/size.d.ts +2 -0
- package/dist/skip.d.ts +35 -0
- package/dist/summary.d.ts +38 -0
- package/dist/sweep.d.ts +7 -0
- package/dist/types.d.ts +458 -0
- package/package.json +14 -52
- package/bin/sweep-nm.mjs +0 -190
- package/dist/cli.js +0 -1699
package/dist/guard.d.ts
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
import { posix } from 'node:path';
|
|
2
|
+
import type { GuardCode } from './codes.js';
|
|
3
|
+
/** 纯判定依赖的最小 path 能力集 (node:path 的 posix / win32 均满足) */
|
|
4
|
+
export type PathOps = Pick<typeof posix, 'sep' | 'basename' | 'relative' | 'isAbsolute' | 'parse' | 'join' | 'resolve' | 'dirname'>;
|
|
5
|
+
export interface PathStyle {
|
|
6
|
+
name: 'posix' | 'win32';
|
|
7
|
+
ops: PathOps;
|
|
8
|
+
/** win32 文件系统大小写不敏感: 一切路径比较前先折叠大小写 */
|
|
9
|
+
caseInsensitive: boolean;
|
|
10
|
+
}
|
|
11
|
+
export declare const POSIX_STYLE: PathStyle;
|
|
12
|
+
export declare const WIN32_STYLE: PathStyle;
|
|
13
|
+
/** 当前平台的判定风格 */
|
|
14
|
+
export declare function nativeStyle(): PathStyle;
|
|
15
|
+
/** 去重键: realpath 折叠后的形态 (不变量 ④ 的比较基准) */
|
|
16
|
+
export declare function dedupeKey(realPath: string, style: PathStyle): string;
|
|
17
|
+
/** 不变量 ①: 路径末段恰为 node_modules (win32 大小写不敏感) */
|
|
18
|
+
export declare function hasNodeModulesLeaf(target: string, style: PathStyle): boolean;
|
|
19
|
+
/**
|
|
20
|
+
* 不变量 ②: realPath 严格位于某个 root 之下。
|
|
21
|
+
* 以 path.relative 语义判定 (禁字符串前缀比较): 结果为空串 (等于 root 本体)、
|
|
22
|
+
* 以 '..' 起头 (上溯逃逸) 或为绝对路径 (win32 跨盘) 均视为不通过。
|
|
23
|
+
*/
|
|
24
|
+
export declare function insideAnyRoot(realPath: string, roots: string[], style: PathStyle): boolean;
|
|
25
|
+
/** 不变量 ③ a: realPath 是文件系统根本体 (posix 的 /、win32 的盘根) */
|
|
26
|
+
export declare function isFilesystemRootBody(realPath: string, style: PathStyle): boolean;
|
|
27
|
+
/** 不变量 ③ b: realPath 是 home 本体; home 传 null 即关闭该防线 */
|
|
28
|
+
export declare function isHomeBody(realPath: string, home: string | null, style: PathStyle): boolean;
|
|
29
|
+
/**
|
|
30
|
+
* 不变量 ⑤ 的判定输入: 根锚点链上单级的形态。
|
|
31
|
+
* `symlink` 由 lstat 判得 (不跟进末段): 链接指向何处、是否悬空, 均不影响判定 ——
|
|
32
|
+
* 「配置拼写的根路径上有符号链接介入」这一事实本身, 就是信任锚可能被换位的证据。
|
|
33
|
+
*/
|
|
34
|
+
export interface AnchorLink {
|
|
35
|
+
/** 该级路径 (拒绝文案的定位依据) */
|
|
36
|
+
path: string;
|
|
37
|
+
/** 该级是否为符号链接 */
|
|
38
|
+
symlink: boolean;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* 不变量 ⑤: 根锚点链 (配置拼写的根及其祖先, 自根的一级子目录至根自身) 不得出现符号链接。
|
|
42
|
+
* 检出首个符号链接即返回其路径 (供拒绝文案定位); 全链为真目录返回 null。
|
|
43
|
+
*
|
|
44
|
+
* 判在「配置拼写」而非 realpath 上的原因: realpath 是同义反复 —— 无论配置里的名字被换成
|
|
45
|
+
* 什么, 它都只报告「此刻的解析结果」, 映射被改动这一事实无处可显; 且复核链与 insideAnyRoot
|
|
46
|
+
* 的比较两侧都取 realpath, 根被换位时一起漂移, 比较恒真。信任锚的完整性只能判在拼写上。
|
|
47
|
+
* 系统固有链接 (macOS 的 /var、/tmp) 同样命中: 用户环境与攻击在拼写层不可区分, 故统一拒,
|
|
48
|
+
* 由用户改写成真实路径形态来表达「我知道这里是什么」(显式即授权, 与 BC-11 的扫描侧同源)。
|
|
49
|
+
*
|
|
50
|
+
* 数据追踪示例:
|
|
51
|
+
* Input links = [
|
|
52
|
+
* { path: '/Users', symlink: false },
|
|
53
|
+
* { path: '/Users/x/ws', symlink: true }, // 根被换成指向他处的符号链接
|
|
54
|
+
* { path: '/Users/x/ws/app', symlink: false }, // 经链接解析到的仍是真目录, 不报
|
|
55
|
+
* ]
|
|
56
|
+
* Output return '/Users/x/ws'
|
|
57
|
+
*
|
|
58
|
+
* 系统固有链接同样命中 (与攻击在拼写层不可区分): root = '/var/w' 时 links[0] 即
|
|
59
|
+
* { path: '/var', symlink: true } → 拒; 改写成 '/private/var/w' 即放行。
|
|
60
|
+
*/
|
|
61
|
+
export declare function firstSymlinkOnAnchor(links: AnchorLink[]): string | null;
|
|
62
|
+
/**
|
|
63
|
+
* 锚链末端 (扫描根 / 任意写入目标) 路径的逐级前缀 (自文件系统根的一级子目录至末端点自身,
|
|
64
|
+
* 末端点含; 文件系统根本身不入链, 它不可能是符号链接): 不变量 ⑤ 的采集坐标。
|
|
65
|
+
* 末端点不拘形态: 目录 (扫描根) 与文件 (写入目标) 走同一条采集, 链语义不因末端点而异。
|
|
66
|
+
* 相对拼写先按注入风格绝对化 (与 lstat 同一坐标系)。
|
|
67
|
+
*
|
|
68
|
+
* 数据追踪示例:
|
|
69
|
+
* Input root = '/Users/x/ws/app' (posix)
|
|
70
|
+
* Output return ['/Users', '/Users/x', '/Users/x/ws', '/Users/x/ws/app']
|
|
71
|
+
*/
|
|
72
|
+
export declare function anchorChainPaths(root: string, style: PathStyle): string[];
|
|
73
|
+
export interface ValidateOptions {
|
|
74
|
+
/**
|
|
75
|
+
* 扫描根 (调用方给定, 须保留配置里的原始拼写): 内部先 realpath 归一供不变量 ② 比较,
|
|
76
|
+
* 原始拼写另供不变量 ⑤ 的锚点链采集 (realpath 会抹掉「名字 → 真实路径」的映射改动)。
|
|
77
|
+
*/
|
|
78
|
+
roots: string[];
|
|
79
|
+
/** home 本体防线; 缺省取 os.homedir(), 显式传 null 关闭 */
|
|
80
|
+
home?: string | null;
|
|
81
|
+
/** path 判定风格; 缺省随当前平台 */
|
|
82
|
+
style?: PathStyle;
|
|
83
|
+
/** 取消信号; 检查点在逐目标之间 */
|
|
84
|
+
signal?: AbortSignal;
|
|
85
|
+
}
|
|
86
|
+
/** 拒绝的结构化上下文 (定位信息做字段, 本地化调用方不必去 message 里抠路径) */
|
|
87
|
+
export interface RejectionDetails {
|
|
88
|
+
/** 原始 errno (realpath 失败类) */
|
|
89
|
+
errno?: string;
|
|
90
|
+
/** 锚点类拒绝: 配置里的根 */
|
|
91
|
+
root?: string;
|
|
92
|
+
/** 锚点类拒绝: 检出符号链接的级 */
|
|
93
|
+
symlink?: string;
|
|
94
|
+
}
|
|
95
|
+
export interface RejectedTarget {
|
|
96
|
+
/** 调用方传入的原始目标 */
|
|
97
|
+
target: string;
|
|
98
|
+
/** 机器可判别的拒绝码 (程序分流只许看它, 严禁对 message 做字符串匹配或前缀解析) */
|
|
99
|
+
code: GuardCode;
|
|
100
|
+
/** 中文人话理由 (文案逐字保留现状) */
|
|
101
|
+
message: string;
|
|
102
|
+
/** 拒绝的结构化上下文 */
|
|
103
|
+
details?: RejectionDetails;
|
|
104
|
+
}
|
|
105
|
+
/** 原始目标 → realpath 归一的配对 (显示侧要原拼写, 删除侧要归一形态) */
|
|
106
|
+
export interface PathMapping {
|
|
107
|
+
/** 调用方传入的拼写 */
|
|
108
|
+
original: string;
|
|
109
|
+
/** realpath 归一形态 */
|
|
110
|
+
real: string;
|
|
111
|
+
}
|
|
112
|
+
export interface ValidationResult {
|
|
113
|
+
/** 通过全部不变量、已 realpath 化并去重的可删目标 (保输入顺序); 空数组即无可删项 */
|
|
114
|
+
accepted: string[];
|
|
115
|
+
/** 未通过的目标与理由, 与输入逐条对应 */
|
|
116
|
+
rejected: RejectedTarget[];
|
|
117
|
+
/** 与 accepted 逐位对应的配对表 (长度与 accepted 相等, mappings[i].real === accepted[i]) */
|
|
118
|
+
mappings: PathMapping[];
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* 任意路径 (写入目标 / 根) 的锚点链上首个符号链接的路径: 采集 (逐级 lstat) 与检出一步到位,
|
|
122
|
+
* 全链为真身或各级均不可核验时返回 null。
|
|
123
|
+
*
|
|
124
|
+
* 与「根」共用同一判定: 链语义不因末端点是目录还是文件而异 (末端点同样入链), 差别只在调用方
|
|
125
|
+
* 拿它判什么 —— 删除侧判信任根 (根被换位), 写入侧判落盘目标 (写入会跟随链接改写其目标);
|
|
126
|
+
* 两侧各自实现即会漂移成「向导放行、`--yes` 全拒」这类实现分家, 故判定标准唯此一处。
|
|
127
|
+
*/
|
|
128
|
+
export declare function firstSymlinkOnTarget(target: string): Promise<string | null>;
|
|
129
|
+
/**
|
|
130
|
+
* 向导逐根校验的入口名 (扫描根锚点链上首个符号链接的路径): 与 `firstSymlinkOnTarget` 同一实现,
|
|
131
|
+
* 保留独立名只因调用点的话术不同 (向导按「扫描根的信任锚」读, 写入侧按「配置的落盘目标」读)。
|
|
132
|
+
* 删除侧不经本入口: 整链判定在 `validateTargets` 内直接消费 `firstSymlinkOnAnchor`, 链头判定另在
|
|
133
|
+
* delete.ts 就地自判 (见其 `isSymlinkHead`)。
|
|
134
|
+
*/
|
|
135
|
+
export declare function firstSymlinkOnRoot(root: string): Promise<string | null>;
|
|
136
|
+
/**
|
|
137
|
+
* 对候选删除目标做五不变量判定。
|
|
138
|
+
*
|
|
139
|
+
* 判定顺序 (逐条短路):
|
|
140
|
+
* 1. 末段不是 node_modules → 拒;
|
|
141
|
+
* 2. realpath 失败 (不存在或不可读) → 拒;
|
|
142
|
+
* 3. realpath 落在根锚点被换位的根下 → 拒 (两侧 realpath 一起漂移, 挑不出别的证据);
|
|
143
|
+
* 4. realpath 是根本体或 home 本体 → 拒;
|
|
144
|
+
* 5. realpath 末段不是 node_modules (符号链接指向别处) → 拒;
|
|
145
|
+
* 6. realpath 不在任何 root 之下 → 拒;
|
|
146
|
+
* 7. realpath 与已通过项重复 → 拒。
|
|
147
|
+
*
|
|
148
|
+
* 数据追踪示例:
|
|
149
|
+
* Input targets = ['/work/zone/app/node_modules', '/work/zone/app']
|
|
150
|
+
* options.roots = ['/work/zone'] (全链为真目录)
|
|
151
|
+
* 步骤 1 首项末段命中, 次项末段为 app 即拒; 首项 realpath 后仍在 zone 之下, 通过
|
|
152
|
+
* Output accepted = ['/work/zone/app/node_modules']
|
|
153
|
+
* rejected = [{ target: '/work/zone/app', message: '路径末段不是 node_modules' }]
|
|
154
|
+
*
|
|
155
|
+
* 分支对照 (根被换位): options.roots = ['/w'], 而 /w 已被换成指向 /evil 的符号链接 →
|
|
156
|
+
* anchors = [{ configured: '/w', real: '/evil', link: '/w' }];
|
|
157
|
+
* target '/w/zone/app/node_modules' 的 real = '/evil/zone/app/node_modules' 命中该锚点 →
|
|
158
|
+
* rejected = [{ target, reason: '根锚点被换位为符号链接 (根: /w; 符号链接: /w), …' }]
|
|
159
|
+
*/
|
|
160
|
+
export declare function validateTargets(targets: string[], options: ValidateOptions): Promise<ValidationResult>;
|
|
161
|
+
/**
|
|
162
|
+
* 设备号探针: 读路径的 st_dev (所在文件系统的设备号)。
|
|
163
|
+
* `follow` 决定 stat 语义 (解析末段符号链接) 还是 lstat 语义 (不解析), 按判定对象分流:
|
|
164
|
+
* 根取 stat (根指向的实际目录才是参照面, 与扫描侧「根为符号链接照常扫描」同向), 目标取 lstat
|
|
165
|
+
* (与 fs.rm 的末段语义对齐 —— 目标是符号链接时 rm 只删链接、不跨设备); 不可核验 (路径消失 /
|
|
166
|
+
* 权限不足) 返回 null。
|
|
167
|
+
*/
|
|
168
|
+
export type DeviceProbe = (path: string, follow: boolean) => Promise<number | null>;
|
|
169
|
+
/** 真实文件系统探针 (缺省实现) */
|
|
170
|
+
export declare const fsDeviceProbe: DeviceProbe;
|
|
171
|
+
export interface CrossDeviceOptions {
|
|
172
|
+
/** 候选目标所属的扫描根 (配置原始拼写, 与目标拼写同源; 归属按最具体根) */
|
|
173
|
+
roots: string[];
|
|
174
|
+
/** 路径判定风味; 缺省随当前平台 */
|
|
175
|
+
style?: PathStyle;
|
|
176
|
+
/** 设备号探针; 缺省读真实文件系统 (测试注入用) */
|
|
177
|
+
probe?: DeviceProbe;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* 跨设备目标的两种形态 (解除路径不同, 故分行呈现):
|
|
181
|
+
* - `on-path`: 挂载点在根与目标之间 (目标所在的整棵子树在另一文件系统上);
|
|
182
|
+
* - `target-itself`: 目标本体即挂载点 (node_modules 被直接挂上了另一卷)。
|
|
183
|
+
*/
|
|
184
|
+
export type CrossDeviceKind = 'on-path' | 'target-itself';
|
|
185
|
+
/** 跨设备目标条目 (保输入顺序; 普通对象, 可 JSON.stringify 进审计) */
|
|
186
|
+
export interface CrossDeviceEntry {
|
|
187
|
+
/** node_modules 绝对路径 */
|
|
188
|
+
target: string;
|
|
189
|
+
/** 跨设备形态 */
|
|
190
|
+
kind: CrossDeviceKind;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* 挑出与所属根不在同一文件系统的目标 (删除面的设备边界闸), 值即形态。
|
|
194
|
+
* 根只是路径上的授权面, 而根之下的挂载点会把另一文件系统的内容带进这条路径 (云盘 / 网络挂载 /
|
|
195
|
+
* 容器卷): 跨设备删除删的是授权路径之外的实际存储, 且删除量与根所在卷的释放量不再是同一口径,
|
|
196
|
+
* 故调用方缺省不进删除批 (设计: docs/designs/deletion-guard.md「设备边界」)。
|
|
197
|
+
*
|
|
198
|
+
* 逐条独立判定, 与安全闸的一票否决整批不同: 挂载点是单个目标的局部事实, 不牵连同根下的其余
|
|
199
|
+
* 目标; 安全闸的不变量否决整批, 是因为那些事实 (根被换位 / 目标逃逸) 会让整批的可信度一起失效。
|
|
200
|
+
* 不可核验 (设备号读不到) 与无归属根的目标不入集: 未检出即无证据, 由安全闸的 realpath 与
|
|
201
|
+
* 删除侧的逐级复核兜底, 不在这里升级成跳过。
|
|
202
|
+
*
|
|
203
|
+
* ### 数据追踪示例
|
|
204
|
+
* ```text
|
|
205
|
+
* Input(真实 Payload)
|
|
206
|
+
* targets = ['/w/plain/node_modules', '/w/vol/proj/node_modules', '/w/onnm/node_modules']
|
|
207
|
+
* options.roots = ['/w']
|
|
208
|
+
* probe: /w → 16777233; /w/plain/node_modules → 16777233;
|
|
209
|
+
* /w/vol → /w/vol/proj → /w/vol/proj/node_modules → 16777253 (挂在根之下的另一文件系统);
|
|
210
|
+
* /w/onnm/node_modules → 16777255 (这一条自身就是挂载点), /w/onnm → 16777233
|
|
211
|
+
*
|
|
212
|
+
* 步骤 1:逐条归属到最具体根 (三条都归属 /w; 无归属根者直接跳过, 归属判定归安全闸)
|
|
213
|
+
*
|
|
214
|
+
* 步骤 2:根设备号每根只探一次 (stat 语义), 目标各自探一次 (lstat 语义) 后比对;
|
|
215
|
+
* 仅对跨设备的目标再探一次其父目录, 以分辨形态 (父目录同设备 = 目标本体即挂载点)
|
|
216
|
+
* plain: 16777233 === 16777233 → 不挑
|
|
217
|
+
* vol/proj: 16777253 !== 16777233, 父目录 /w/vol/proj 亦为 16777253 → on-path
|
|
218
|
+
* onnm: 16777255 !== 16777233, 父目录 /w/onnm 为 16777233 → target-itself
|
|
219
|
+
*
|
|
220
|
+
* Output(数据契约)
|
|
221
|
+
* return Map { '/w/vol/proj/node_modules' → 'on-path',
|
|
222
|
+
* '/w/onnm/node_modules' → 'target-itself' }
|
|
223
|
+
* ```
|
|
224
|
+
*/
|
|
225
|
+
export declare function findCrossDeviceTargets(targets: string[], options: CrossDeviceOptions): Promise<CrossDeviceEntry[]>;
|
|
226
|
+
/**
|
|
227
|
+
* 跨设备条目数组 → 查询索引 (供需要 has / get 的消费方: skip.ts 三个函数的第二参形态)。
|
|
228
|
+
* 与 findCrossDeviceTargets 的数组形态配套: 落盘用数组, 查询用索引。
|
|
229
|
+
*/
|
|
230
|
+
export declare function crossDeviceIndex(entries: readonly CrossDeviceEntry[]): ReadonlyMap<string, CrossDeviceKind>;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* API 包入口。导出面分两部分, 均以 docs/designs/api-surface.md 为契约基准:
|
|
3
|
+
* - 公开面新增: 错误模型 (SweepError / code 体系) 与域类型 (编排层 / 跳过集册 / 诊断),
|
|
4
|
+
* 按设计文档 §3 / §5 / §7 落地;
|
|
5
|
+
* - 现状能力搬运: 原语层函数与既有类型, 随实现工序逐刀对齐设计 (编排层 createSweeper
|
|
6
|
+
* 见 sweep.ts, 结果缝合层见 summary.ts, 展示辅助见 display.ts; 设计 §2.6 / §2.7 / §4 / §7.8)。
|
|
7
|
+
*/
|
|
8
|
+
export { type AbortCode, type GuardCode, type RemoveFailureCode, type ScanWarningCode, type SizeBasis, type SizeWarningCode, type SkipReason, type SweepErrorCode, type SweepPhase, type SweepWarningCode, type UnmeasuredCode, } from './codes.js';
|
|
9
|
+
export { type Classification, type ClassifyOptions, type TargetKind, classifyTarget, } from './classify.js';
|
|
10
|
+
export { type Config, type ConfigSource, type EnvTable, type LoadConfigResult, type ResolveConfigPathOptions, type ResolvedConfigPath, DEFAULT_EXCLUDE, loadConfig, loadResolvedConfig, mergeNames, resolveConfigPath, } from './config.js';
|
|
11
|
+
export { type AbortedBatch, type BatchOutcome, type RemoveBatchOptions, type RemovalOptions, type RemovalProgressEvent, type RemovalResult, type TargetFailure, type TrustRoot, removeBatch, removeTargets, toTrustRoots, } from './delete.js';
|
|
12
|
+
export { formatBytes, sanitizeLine, sanitizeOutputLine } from './display.js';
|
|
13
|
+
export { SweepError, type SweepErrorDetails, isSweepError } from './errors.js';
|
|
14
|
+
export { type AnchorLink, type CrossDeviceEntry, type CrossDeviceKind, type CrossDeviceOptions, type DeviceProbe, type PathMapping, type PathOps, type PathStyle, type RejectedTarget, type RejectionDetails, type ValidateOptions, type ValidationResult, POSIX_STYLE, WIN32_STYLE, anchorChainPaths, crossDeviceIndex, dedupeKey, findCrossDeviceTargets, firstSymlinkOnAnchor, firstSymlinkOnRoot, firstSymlinkOnTarget, fsDeviceProbe, hasNodeModulesLeaf, insideAnyRoot, isFilesystemRootBody, isHomeBody, nativeStyle, validateTargets, } from './guard.js';
|
|
15
|
+
export { createScanner } from './scan.js';
|
|
16
|
+
export { createSizer } from './size.js';
|
|
17
|
+
export { collectSkips, crossDeviceNote, deletionBatch, skipReasonOf, skipsBatch, toSkipCandidates, } from './skip.js';
|
|
18
|
+
export { isSuccessOutcome, summarizeReport } from './summary.js';
|
|
19
|
+
export { createSweeper } from './sweep.js';
|
|
20
|
+
export type { EntryOutcome, EntryOutcomeKind, MeasureOptions, MeasureProgressEvent, NameMatch, ResolvedSweepOptions, ScanHit, ScanOptions, ScanProgressEvent, ScanResult, Scanner, SizeEntry, SizeResult, Sizer, SkipBook, SkipCandidate, SkippedTarget, SweepDrift, SweepEntry, SweepOptions, SweepOutcomeEntry, SweepPlan, SweepPlanOptions, SweepPolicy, SweepProgressEvent, SweepReport, SweepRunOptions, SweepRunStatus, SweepSummary, Sweeper, SweepWarning, UnmeasuredEntry, } from './types.js';
|