@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/README.md +22 -19
- package/README.zh-CN.md +164 -161
- package/dist/codes.d.ts +3 -1
- package/dist/delete.d.ts +3 -11
- package/dist/display.d.ts +1 -1
- package/dist/errors.d.ts +39 -24
- package/dist/guard.d.ts +9 -7
- package/dist/index.d.ts +3 -3
- package/dist/index.js +747 -329
- package/dist/manifest.json +3 -3
- package/dist/scan.d.ts +2 -6
- package/dist/skip.d.ts +1 -1
- package/dist/summary.d.ts +4 -1
- package/dist/types.d.ts +15 -9
- package/package.json +8 -5
- package/dist/runtime.d.ts +0 -26
- package/dist/scan-native.d.ts +0 -2
- package/dist/scan-parallel.d.ts +0 -2
- package/dist/scan-prune.d.ts +0 -2
- package/dist/size-du.d.ts +0 -33
- package/dist/size-js.d.ts +0 -2
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# sweep-node-modules
|
|
2
2
|
|
|
3
|
-
[](https://github.com/iyowei/clis/actions/workflows/ci.yml)
|
|
4
4
|
[](https://www.npmjs.com/package/@iyowei/sweep-node-modules)
|
|
5
5
|
[](https://www.npmjs.com/package/@iyowei/sweep-node-modules)
|
|
6
6
|

|
|
7
|
-

|
|
8
8
|
|
|
9
9
|
**English** | [中文](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -30,8 +30,8 @@ Programmable API to sweep `node_modules` across workspace roots: scan, measure,
|
|
|
30
30
|
## Requirements
|
|
31
31
|
|
|
32
32
|
- **Dual runtime**: bun first, node fallback (identical behavior; bun starts faster). Node floor: `>= 22.18.0` (this package's `engines` field).
|
|
33
|
-
- Zero third-party runtime dependencies: built-in runtime capabilities only (see [ADR 0003](
|
|
34
|
-
- Windows, macOS, and Linux (see [ADR 0007](
|
|
33
|
+
- Zero third-party runtime dependencies: built-in runtime capabilities only (see [ADR 0003](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/adrs/0003-zero-runtime-deps.md)).
|
|
34
|
+
- Windows, macOS, and Linux (see [ADR 0007](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/adrs/0007-platform-portability.md)).
|
|
35
35
|
- Written in TypeScript; type declarations ship with the package.
|
|
36
36
|
|
|
37
37
|
## Installation
|
|
@@ -114,7 +114,7 @@ Creates the orchestrator: the whole chain behind one object. A second instance c
|
|
|
114
114
|
- `plan(options?)`: the read-only pass, see below.
|
|
115
115
|
- `run(options?)`: the executing pass, see below.
|
|
116
116
|
|
|
117
|
-
Parameter errors
|
|
117
|
+
Parameter errors — empty `roots`, relative paths in `roots` (on win32, drive-relative paths like `/app` or `\app` are also rejected), empty-string or non-string items in `roots` / `exclude` / `include`, `home === ''`, or non-boolean `policy.releaseSuspects` — **throw synchronously** (`SweepError('INVALID_ARGUMENT', ..., { field })`) at construction: fail fast, before any IO. Every asynchronous entry point below rejects its promise instead.
|
|
118
118
|
|
|
119
119
|
- The name lists take the same merge the CLI applies (`mergeNames`): duplicates dropped, and `node_modules` / `.git` silently removed since a name can never take effect there.
|
|
120
120
|
- `policy.releaseSuspects` is the library-side `--force`: it lets suspected install trees into the delete batch, releases only that category, and relaxes no guard invariant. Cross-device targets are unaffected either way.
|
|
@@ -143,6 +143,7 @@ The read-only pass: scan + measure + classify + device check + batch constructio
|
|
|
143
143
|
- `entries` `SweepEntry[]`: one entry per hit that still exists at measure time (a hit gone by then produces no entry; see `gone` in `SizeResult`): `target` / `project` / `root` / `bytes?` / `basis?` / `kind` / `kindReason?` / `crossDevice?` / `unmeasuredCode?` / `unmeasuredReason?` / `inBatch`, plus `skipReason` and `skipNote` when out of the batch (the code and the human note travel on the entry, so a review table needs no join).
|
|
144
144
|
- `batch` `string[]`: the targets that would be deleted, in list order.
|
|
145
145
|
- `skipped` `SkippedTarget[]`: every out-of-batch target with its `reason` and `note`.
|
|
146
|
+
- `trailer?` `string[]`: closing summary lines for skipped categories (same source as `SkipBook.trailer`, one line per category or cross-device form that occurred; empty array when nothing was skipped).
|
|
146
147
|
- `warnings` `SweepWarning[]`: non-fatal scan / size warnings (`{ code, message, path?, errno? }`); `code` is a `SweepWarningCode`, the union of `ScanWarningCode` and `SizeWarningCode`.
|
|
147
148
|
- `nameMatches`: `{ exclude: NameMatch[]; include: NameMatch[] }`, per-name hit counts for both lists, so a name that never matched (a typo) is visible before it matters.
|
|
148
149
|
|
|
@@ -320,7 +321,7 @@ The invariants are judged per target with early exit: the leaf must be exactly `
|
|
|
320
321
|
|
|
321
322
|
- `targets` `string[]`
|
|
322
323
|
- `options` `CrossDeviceOptions`:
|
|
323
|
-
- `roots` `string[]` (required): the owning root of a target is the
|
|
324
|
+
- `roots` `string[]` (required): the owning root of a target is the innermost root containing it under strict path-containment order (`insideAnyRoot`, unaffected by literal string length from redundant separators).
|
|
324
325
|
- `style?` `PathStyle`: path flavor; native by default.
|
|
325
326
|
- `probe?` `DeviceProbe`: the device-number probe; defaults to `fsDeviceProbe` (inject to test cross-device flows on one filesystem).
|
|
326
327
|
- Returns: `Promise<CrossDeviceEntry[]>`: `{ target, kind }` entries in input order; an empty array when nothing is cross-device.
|
|
@@ -352,7 +353,7 @@ The guard's path layer, exposed for tests and custom flows. Every predicate take
|
|
|
352
353
|
#### `POSIX_STYLE` / `WIN32_STYLE`
|
|
353
354
|
|
|
354
355
|
- `PathStyle` constants, ready for injection: `WIN32_STYLE` folds case before every comparison; `POSIX_STYLE` does not.
|
|
355
|
-
- `PathStyle`: `{ name: 'posix' | 'win32', ops: PathOps, caseInsensitive: boolean }`, where `PathOps` is the minimal path capability set (`sep` / `basename` / `relative` / `isAbsolute` / `parse` / `join` / `resolve` / `dirname`), satisfied by both `node:path` flavors.
|
|
356
|
+
- `PathStyle`: `{ name: 'posix' | 'win32', ops: PathOps, caseInsensitive: boolean }`, where `PathOps` is the minimal path capability set (`sep` / `basename` / `relative` / `isAbsolute` / `parse` / `join` / `resolve` / `dirname` / `normalize`), satisfied by both `node:path` flavors.
|
|
356
357
|
|
|
357
358
|
#### `nativeStyle(): PathStyle`
|
|
358
359
|
|
|
@@ -419,15 +420,16 @@ Collection (a per-level `lstat` walk) and detection in one call. The write side
|
|
|
419
420
|
- `targets` `string[]`: guard-validated targets (realpath form).
|
|
420
421
|
- `options` `RemovalOptions`:
|
|
421
422
|
- `roots` `TrustRoot[]` (required): the trust roots that own the targets; a target under none of them aborts the batch.
|
|
423
|
+
- `style?` `PathStyle`: path flavor (win32 case folding and separator semantics); native by default.
|
|
422
424
|
- `signal?` `AbortSignal`: checked between entries (the mid-`rm` rule is in [Progress and cancellation](#progress-and-cancellation)).
|
|
423
425
|
- `onProgress?` `(event: RemovalProgressEvent) => void`: one event per entry leaving its bucket (`removed` / `missing` / `failed` / `aborted`).
|
|
424
426
|
- Returns: `Promise<RemovalResult>`:
|
|
425
427
|
- `removed` `string[]`: deleted, input order kept.
|
|
426
428
|
- `missing` `string[]`: `rm` reported ENOENT and a re-check confirmed the target itself is gone (counted as success, input order kept).
|
|
427
429
|
- `failed` `TargetFailure[]`: `{ target, code, errno?, message, partialRisk }`, with `code` a `RemoveFailureCode`; `partialRisk: true` means content may be partially deleted, so flag it for human review (a `partialRisk: false` failure never attempted a deletion).
|
|
428
|
-
- `aborted?` `AbortedBatch`: the
|
|
430
|
+
- `aborted?` `AbortedBatch`: the pre-removal check failed mid-batch (`{ target, code, message, path? }`, with `code` an `AbortCode`); dispatching stops immediately (already in-flight entries in the 4-way concurrency window finish and are reported truthfully, while undispatched entries are never touched).
|
|
429
431
|
|
|
430
|
-
Right before removing each target, the chain from
|
|
432
|
+
Before touching disk, `removeTargets` synchronously hard-rejects malformed targets — trailing separators (`/` or `\`), relative `.` / `..` segments, a non-`node_modules` leaf, or a target outside every `roots[].real` — aborting the batch with `REVIEW_NOT_UNDER_ANY_ROOT`. Right before removing each target, it `lstat`-verifies the owning root's full ancestor chain (both `configured` and `real`, deduplicated) and then every component from `root.real` down to the target's parent: any non-directory (symlink included) aborts the batch (`REVIEW_HEAD_SYMLINK` / `REVIEW_COMPONENT_REPLACED`), and any vanished or unverifiable level fails closed on that entry (`REVIEW_COMPONENT_VANISHED` / `REVIEW_UNVERIFIED`, `partialRisk: false`, zero deletion).
|
|
431
433
|
|
|
432
434
|
```ts
|
|
433
435
|
const removal = await removeTargets(accepted, {
|
|
@@ -576,23 +578,23 @@ One rule decides the channel: **failures that can be listed are returned; failur
|
|
|
576
578
|
|
|
577
579
|
### `SweepError`
|
|
578
580
|
|
|
579
|
-
- `class SweepError extends Error`: `{ name: 'SweepError', code, message, details? }`.
|
|
581
|
+
- `class SweepError<Code extends SweepErrorCode = SweepErrorCode> extends Error`: `{ name: 'SweepError', code, message, details? }`.
|
|
580
582
|
- `code` `SweepErrorCode`: `CONFIG_READ_FAILED` / `CONFIG_CORRUPT_JSON` / `CONFIG_CORRUPT_SHAPE` / `CONFIG_ABSENT` / `INVALID_ARGUMENT` / `CANCELLED`.
|
|
581
583
|
- `message` `string`: the readable text (see the code rules below).
|
|
582
584
|
- `details?` `SweepErrorDetails`: a discriminated union keyed by `code`: `{ path, errno? }`, `{ path }`, `{ path, field }`, `{ path, source }`, `{ field }`, `{ phase, partial? }`.
|
|
583
|
-
- Constructor: `new SweepError(code, message, details?)
|
|
585
|
+
- Constructor: `new SweepError(code, message, details?, options?)` (`options` accepts standard `ErrorOptions`, e.g. `{ cause }`).
|
|
584
586
|
- The only class in the package: every other instance comes from a `createXxx()` factory, and every domain datum is a plain object.
|
|
585
587
|
|
|
586
|
-
### `isSweepError(value): value is
|
|
588
|
+
### `isSweepError(value): value is NarrowedSweepError` / `isSweepErrorCode(value, code)`
|
|
587
589
|
|
|
588
|
-
- `value` `
|
|
589
|
-
-
|
|
590
|
+
- `isSweepError(value)`: shape-based check (`name === 'SweepError'`, known `code`, and `typeof message === 'string'`; `instanceof Error` is not required), narrowing `details` by `code`.
|
|
591
|
+
- `isSweepErrorCode(value, code)`: narrows `value` directly to `SweepError<C>` with its exact `SweepErrorDetailsByCode[C]`.
|
|
590
592
|
|
|
591
593
|
In packaged or multi-instance environments (where two copies of the library can coexist in one process), `instanceof SweepError` gives false negatives; use the shape-based guard there. Unexpected internal exceptions are not wrapped: they bubble unchanged.
|
|
592
594
|
|
|
593
595
|
### Code families
|
|
594
596
|
|
|
595
|
-
Domain codes by family (the full trigger table per code lives in the [API surface design](
|
|
597
|
+
Domain codes by family (the full trigger table per code lives in the [API surface design](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/api-surface.md)):
|
|
596
598
|
|
|
597
599
|
```text
|
|
598
600
|
Guard (validateTargets → rejected[].code)
|
|
@@ -666,10 +668,11 @@ The library has no `watch()` async iterator: the CLI consumes callbacks directly
|
|
|
666
668
|
|
|
667
669
|
## Development
|
|
668
670
|
|
|
669
|
-
Environment setup, common commands, dual-runtime verification, and commit hooks: see the [development guide](
|
|
671
|
+
Environment setup, common commands, dual-runtime verification, and commit hooks: see the [development guide](https://github.com/iyowei/clis/blob/main/docs/development.md). This package lives in the `packages/sweep-node-modules` directory of that repository.
|
|
670
672
|
|
|
671
673
|
## Documentation
|
|
672
674
|
|
|
673
|
-
- [Engineering documentation index](
|
|
674
|
-
- [
|
|
675
|
-
- [
|
|
675
|
+
- [Engineering documentation index](https://github.com/iyowei/clis/blob/main/docs/README.md)
|
|
676
|
+
- [Product docs & ADRs](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/README.md)
|
|
677
|
+
- [API surface design](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/api-surface.md): the authoritative export surface, error codes, and behavior contracts behind this page
|
|
678
|
+
- [Safety guardrails](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/safety-guardrails.md), the full account (in Chinese)
|