@iyowei/sweep-node-modules 0.5.1 → 1.0.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.
package/dist/codes.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 判别值与枚举的类型集: 错误码 / 告警码 / 跳过原因 / 体积口径 / 编排阶段。
3
3
  *
4
- * 契约基准: docs/designs/api-surface.md §3.2 与 §7.3。
4
+ * 契约基准: packages/sweep-node-modules/docs/designs/api-surface.md §3.2 与 §7.3。
5
5
  * 命名规则: `<域>_<判定>`, 全大写蛇形; 域取自模块 (SCAN / SIZE / GUARD / REMOVE / CONFIG / REVIEW; 另有无域项 INVALID_ARGUMENT 与 CANCELLED)。
6
6
  * 硬纪律: **code 一经发布即冻结, 只增不改** (废弃走文档标注, 不回收取值);
7
7
  * 且同一个 code 不得合并「处置方向相反」的语义 (调用方必须能不读 message 就决定下一步)。
@@ -24,6 +24,8 @@ export type GuardCode = 'GUARD_LEAF_NOT_NODE_MODULES' | 'GUARD_TARGET_MISSING' |
24
24
  export type RemoveFailureCode = 'REMOVE_FAILED' | 'REMOVE_ENOENT_SURVIVOR' | 'REVIEW_UNVERIFIED' | 'REVIEW_COMPONENT_VANISHED';
25
25
  /** 整批中止码 (复核阶段的致命信号) */
26
26
  export type AbortCode = 'REVIEW_NOT_UNDER_ANY_ROOT' | 'REVIEW_HEAD_SYMLINK' | 'REVIEW_COMPONENT_REPLACED';
27
+ /** 批次内未尝试码: 删除阶段复核整批中止 (AbortCode), 或安全闸整批拒绝连带未删 ('BATCH_REJECTED') */
28
+ export type NotAttemptedCode = AbortCode | 'BATCH_REJECTED';
27
29
  /** 库抛出的错误码 (配置 / 参数 / 取消三档共用, 见 errors.ts 的 SweepError) */
28
30
  export type SweepErrorCode = 'CONFIG_READ_FAILED' | 'CONFIG_CORRUPT_JSON' | 'CONFIG_CORRUPT_SHAPE' | 'CONFIG_ABSENT' | 'INVALID_ARGUMENT' | 'CANCELLED';
29
31
  /**
package/dist/delete.d.ts CHANGED
@@ -33,7 +33,7 @@ export interface RemovalResult {
33
33
  missing: string[];
34
34
  /** 删除失败与复核未完成 (组件消失 / 不可核验) 的目标及原因 (保输入顺序); 后者未执行删除 */
35
35
  failed: TargetFailure[];
36
- /** 安全复核未通过即中止整批, 其间条目一律不删; 未触发时缺省 */
36
+ /** 安全复核未通过即中止整批 (触发后停止派发新条目, 并发窗口内已派发条目会完成并如实报告); 未触发时缺省 */
37
37
  aborted?: AbortedBatch;
38
38
  }
39
39
  /** 删除操作的进度事件 (每条目标出桶即发一条) */
@@ -65,6 +65,8 @@ export interface RemovalOptions {
65
65
  * `configured` 供链头判定。目标不在任何根之下时无可信复核, 整批中止。
66
66
  */
67
67
  roots: TrustRoot[];
68
+ /** 路径判定风味 (win32 大小写折叠与分隔符语义); 缺省随当前平台 */
69
+ style?: PathStyle;
68
70
  /** 取消信号; 只在条目之间检查, 绝不在单条 rm 中途中断 (那会制造新的半删状态) */
69
71
  signal?: AbortSignal;
70
72
  /** 进度回调; 粒度: 每条目标出桶即发一条 */
@@ -125,16 +127,6 @@ export interface RemoveBatchOptions {
125
127
  */
126
128
  staleTargets?: 'reject' | 'missing';
127
129
  }
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
130
  /** 整批拒绝与已执行二选一 (BC-22 的判别联合表达) */
139
131
  export type BatchOutcome = {
140
132
  status: 'rejected';
package/dist/display.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * 展示辅助 (纯函数, 零 IO, 无打印): 人类可读体积与输出面净化。
3
- * 契约基准: docs/designs/api-surface.md §2.6; OF-14 的「唯一实现」义务落此 ——
3
+ * 契约基准: packages/sweep-node-modules/docs/designs/api-surface.md §2.6; OF-14 的「唯一实现」义务落此 ——
4
4
  * 全输出面 (CLI 清单 / 诊断 stderr / config 报告 / 向导 / 帮助 / 内嵌方) 共用同一实现,
5
5
  * 各面一律经此, 严禁另写一份。本模块自 CLI 包 render.ts 上移 (逻辑逐字未动),
6
6
  * render.ts 转出转发以保持既有消费方写法不变。
package/dist/errors.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 库抛出的唯一错误类型与判别工具。
3
3
  *
4
- * 契约基准: docs/designs/api-surface.md §3.6。
4
+ * 契约基准: packages/sweep-node-modules/docs/designs/api-surface.md §3.6。
5
5
  * 两条通道的划分 (§3.1): 能列出结果的失败走返回值 (拒绝 / 失败 / 中止 / 未测到 / 跳过);
6
6
  * 无法开始或无法继续的失败 (配置 / 参数 / 取消) 才抛 SweepError。
7
7
  * 本类是全仓「以 createXxx() 工厂交出实例、不导出类」惯例的唯一例外:
@@ -10,34 +10,49 @@
10
10
  import type { SweepErrorCode, SweepPhase } from './codes.js';
11
11
  import type { ConfigSource } from './config.js';
12
12
  import type { RemovalResult } from './delete.js';
13
+ /** 按 code 索引的错误上下文映射 (支持按 code 精确收窄 details) */
14
+ export interface SweepErrorDetailsByCode {
15
+ CONFIG_READ_FAILED: {
16
+ path: string;
17
+ errno?: string;
18
+ };
19
+ CONFIG_CORRUPT_JSON: {
20
+ path: string;
21
+ };
22
+ CONFIG_CORRUPT_SHAPE: {
23
+ path: string;
24
+ field: string;
25
+ };
26
+ CONFIG_ABSENT: {
27
+ path: string;
28
+ source: ConfigSource;
29
+ };
30
+ INVALID_ARGUMENT: {
31
+ field: string;
32
+ };
33
+ CANCELLED: {
34
+ phase: SweepPhase;
35
+ partial?: RemovalResult;
36
+ };
37
+ }
13
38
  /** 抛错附带的上下文: 判别联合, 按 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
- };
39
+ export type SweepErrorDetails = SweepErrorDetailsByCode[keyof SweepErrorDetailsByCode];
31
40
  /** 库抛出的唯一错误类型 (config / 参数 / 取消三档共用) */
32
- export declare class SweepError extends Error {
41
+ export declare class SweepError<Code extends SweepErrorCode = SweepErrorCode> extends Error {
33
42
  readonly name: 'SweepError';
34
- readonly code: SweepErrorCode;
35
- readonly details?: SweepErrorDetails;
36
- constructor(code: SweepErrorCode, message: string, details?: SweepErrorDetails);
43
+ readonly code: Code;
44
+ readonly details?: SweepErrorDetailsByCode[Code];
45
+ constructor(code: Code, message: string, details?: SweepErrorDetailsByCode[Code], options?: ErrorOptions);
37
46
  }
47
+ /** 按 code 展开的判别联合: `if (isSweepError(e) && e.code === 'CANCELLED') e.details?.partial` 直接收窄 */
48
+ export type NarrowedSweepError = {
49
+ [K in SweepErrorCode]: SweepError<K>;
50
+ }[SweepErrorCode];
38
51
  /**
39
- * 类型守卫: 不依赖类身份, 走「Error 形状 + name + code 取值」判别。
52
+ * 类型守卫: 不依赖类身份, 走「Error 形状 + name + message + code 取值」判别。
40
53
  * 扩展 / 打包环境里同一进程可能存在两份库实例, 此时 instanceof SweepError 会假阴;
41
54
  * 需要跨实例判别的调用方一律用它。
42
55
  */
43
- export declare function isSweepError(value: unknown): value is SweepError;
56
+ export declare function isSweepError(value: unknown): value is NarrowedSweepError;
57
+ /** 单步按 code 收窄守卫: 校验为 SweepError 且 code 匹配时直接窄化到对应 details 分支 */
58
+ export declare function isSweepErrorCode<Code extends SweepErrorCode>(value: unknown, code: Code): value is SweepError<Code>;
package/dist/guard.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { posix } from 'node:path';
2
2
  import type { GuardCode } from './codes.js';
3
3
  /** 纯判定依赖的最小 path 能力集 (node:path 的 posix / win32 均满足) */
4
- export type PathOps = Pick<typeof posix, 'sep' | 'basename' | 'relative' | 'isAbsolute' | 'parse' | 'join' | 'resolve' | 'dirname'>;
4
+ export type PathOps = Pick<typeof posix, 'sep' | 'basename' | 'relative' | 'isAbsolute' | 'parse' | 'join' | 'resolve' | 'dirname' | 'normalize'>;
5
5
  export interface PathStyle {
6
6
  name: 'posix' | 'win32';
7
7
  ops: PathOps;
@@ -22,9 +22,9 @@ export declare function hasNodeModulesLeaf(target: string, style: PathStyle): bo
22
22
  * 以 '..' 起头 (上溯逃逸) 或为绝对路径 (win32 跨盘) 均视为不通过。
23
23
  */
24
24
  export declare function insideAnyRoot(realPath: string, roots: string[], style: PathStyle): boolean;
25
- /** 不变量 ③ a: realPath 是文件系统根本体 (posix 的 /、win32 的盘根) */
25
+ /** 不变量 ③ a: realPath 是文件系统根本体 (posix 的 /、win32 的盘根; 先 normalize 消去正斜杠与冗余分隔符) */
26
26
  export declare function isFilesystemRootBody(realPath: string, style: PathStyle): boolean;
27
- /** 不变量 ③ b: realPath 是 home 本体; home 传 null 即关闭该防线 */
27
+ /** 不变量 ③ b: realPath 是 home 本体 (用 relative === '' 消去尾分隔符与正反斜杠差异); home 传 null 即关闭该防线 */
28
28
  export declare function isHomeBody(realPath: string, home: string | null, style: PathStyle): boolean;
29
29
  /**
30
30
  * 不变量 ⑤ 的判定输入: 根锚点链上单级的形态。
@@ -155,7 +155,7 @@ export declare function firstSymlinkOnRoot(root: string): Promise<string | null>
155
155
  * 分支对照 (根被换位): options.roots = ['/w'], 而 /w 已被换成指向 /evil 的符号链接 →
156
156
  * anchors = [{ configured: '/w', real: '/evil', link: '/w' }];
157
157
  * target '/w/zone/app/node_modules' 的 real = '/evil/zone/app/node_modules' 命中该锚点 →
158
- * rejected = [{ target, reason: '根锚点被换位为符号链接 (根: /w; 符号链接: /w), …' }]
158
+ * rejected = [{ target, code: 'GUARD_ROOT_ANCHOR_SYMLINK', message: '根锚点被换位为符号链接 (根: /w; 符号链接: /w), …' }]
159
159
  */
160
160
  export declare function validateTargets(targets: string[], options: ValidateOptions): Promise<ValidationResult>;
161
161
  /**
@@ -193,7 +193,7 @@ export interface CrossDeviceEntry {
193
193
  * 挑出与所属根不在同一文件系统的目标 (删除面的设备边界闸), 值即形态。
194
194
  * 根只是路径上的授权面, 而根之下的挂载点会把另一文件系统的内容带进这条路径 (云盘 / 网络挂载 /
195
195
  * 容器卷): 跨设备删除删的是授权路径之外的实际存储, 且删除量与根所在卷的释放量不再是同一口径,
196
- * 故调用方缺省不进删除批 (设计: docs/designs/deletion-guard.md「设备边界」)。
196
+ * 故调用方缺省不进删除批 (设计: docs/sweep/designs/deletion-guard.md「设备边界」)。
197
197
  *
198
198
  * 逐条独立判定, 与安全闸的一票否决整批不同: 挂载点是单个目标的局部事实, 不牵连同根下的其余
199
199
  * 目标; 安全闸的不变量否决整批, 是因为那些事实 (根被换位 / 目标逃逸) 会让整批的可信度一起失效。
@@ -218,8 +218,10 @@ export interface CrossDeviceEntry {
218
218
  * onnm: 16777255 !== 16777233, 父目录 /w/onnm 为 16777233 → target-itself
219
219
  *
220
220
  * Output(数据契约)
221
- * return Map { '/w/vol/proj/node_modules' → 'on-path',
222
- * '/w/onnm/node_modules' → 'target-itself' }
221
+ * return [
222
+ * { target: '/w/vol/proj/node_modules', kind: 'on-path' },
223
+ * { target: '/w/onnm/node_modules', kind: 'target-itself' },
224
+ * ]
223
225
  * ```
224
226
  */
225
227
  export declare function findCrossDeviceTargets(targets: string[], options: CrossDeviceOptions): Promise<CrossDeviceEntry[]>;
package/dist/index.d.ts CHANGED
@@ -1,16 +1,16 @@
1
1
  /**
2
- * API 包入口。导出面分两部分, 均以 docs/designs/api-surface.md 为契约基准:
2
+ * API 包入口。导出面分两部分, 均以 packages/sweep-node-modules/docs/designs/api-surface.md 为契约基准:
3
3
  * - 公开面新增: 错误模型 (SweepError / code 体系) 与域类型 (编排层 / 跳过集册 / 诊断),
4
4
  * 按设计文档 §3 / §5 / §7 落地;
5
5
  * - 现状能力搬运: 原语层函数与既有类型, 随实现工序逐刀对齐设计 (编排层 createSweeper
6
6
  * 见 sweep.ts, 结果缝合层见 summary.ts, 展示辅助见 display.ts; 设计 §2.6 / §2.7 / §4 / §7.8)。
7
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';
8
+ export { type AbortCode, type GuardCode, type NotAttemptedCode, type RemoveFailureCode, type ScanWarningCode, type SizeBasis, type SizeWarningCode, type SkipReason, type SweepErrorCode, type SweepPhase, type SweepWarningCode, type UnmeasuredCode, } from './codes.js';
9
9
  export { type Classification, type ClassifyOptions, type TargetKind, classifyTarget, } from './classify.js';
10
10
  export { type Config, type ConfigSource, type EnvTable, type LoadConfigResult, type ResolveConfigPathOptions, type ResolvedConfigPath, DEFAULT_EXCLUDE, loadConfig, loadResolvedConfig, mergeNames, resolveConfigPath, } from './config.js';
11
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
12
  export { formatBytes, sanitizeLine, sanitizeOutputLine } from './display.js';
13
- export { SweepError, type SweepErrorDetails, isSweepError } from './errors.js';
13
+ export { type NarrowedSweepError, SweepError, type SweepErrorDetails, type SweepErrorDetailsByCode, isSweepError, isSweepErrorCode, } from './errors.js';
14
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
15
  export { createScanner } from './scan.js';
16
16
  export { createSizer } from './size.js';