void-purge

Purge orphaned signal fragments from your archival nodes

A minimal, fast protocol for identifying and removing orphaned artifacts (unused dependencies) and corrupted transmissions (deprecated packages) from Node.js archival nodes. Scans large projects in under a second.

About

In the Signal Archives, every dependency is a signal fragment—a piece of transmitted knowledge preserved in your project manifest. Over time, some fragments become orphaned: referenced in manifests but no longer actively used in transmission patterns (code).

void-purge scans your codebase for these orphaned artifacts, helping maintain archival integrity by removing fragments that no longer serve the network.

Features

• Detect orphaned artifacts - finds unused signal fragments in archival manifests
• Identify duplicate fragments - spots artifacts listed in multiple manifest locations
• Scan for corrupted transmissions - warns about deprecated packages via NPM registry
• Safe by default - uses preview mode; requires --remove flag to purge
• Fast signal analysis - scans large archives in under a second
• Clean archival reports - clear, color-coded output with detailed analysis

Installation

npm install -g void-purge

Or run directly without installing:

npx void-purge

Usage

Scan current project

void-purge

Output:

◆ VOID-PURGE — Signal Purge Protocol
→ Scanning transmission logs...
✓ Detected 12 active signal patterns
→ Cross-referencing archival manifests...
→ Checking for corrupted transmissions...

◆ Archival Status Report
◆ Orphaned Artifacts (3)
  ● @types/jest — No active signal reference
  ● @types/node — Transmission path severed
  ● ts-jest — Fragment isolation confirmed

→ Execute with --remove to purge orphaned artifacts

Remove orphaned artifacts

void-purge --remove

This will:

1. Purge unused packages from your package.json
2. Show which orphaned artifacts were removed
3. Suggest running npm install to update cache

Show detailed analysis

void-purge --verbose

Displays detailed information about all signal patterns, archival manifests, and analysis results.

Preserve specific signal fragments

void-purge --keep lodash react

Excludes specified packages from purging (even if unused/orphaned).

Scan a different archival node

void-purge /path/to/project

Combine protocol options

void-purge /path/to/project --remove --verbose --keep lodash

Preview changes with detailed analysis

void-purge --verbose

Shows what would be purged before applying changes with --remove.

Integration with build pipelines

Add to your package.json:

{
  "scripts": {
    "archive:audit": "void-purge",
    "archive:verify": "void-purge --verbose",
    "archive:purge": "void-purge --remove"
  }
}

Then run:

npm run archive:verify      # Preview orphaned artifacts
npm run archive:purge       # Purge from manifest

CI/CD Integration

Verify archival integrity in your pipeline:

# Scan for orphaned artifacts; fails if any detected
void-purge --verbose

Exit code will be non-zero if orphaned artifacts exist (useful for CI gates).

Configuration

Create a void-purge.config.json file in your project root to set archival preservation rules:

{
  "keep": ["lodash", "moment"]
}

Example configurations:

For a React application node:

{
  "keep": ["react", "react-dom", "react-router-dom"]
}

For a monorepo network:

{
  "keep": ["@company/shared-utils", "@company/types"]
}

For a library with peer fragment dependencies:

{
  "keep": ["tslib", "@types/node"]
}

How it works

1. Scans all .js, .ts, .jsx, .tsx files in your archival node
2. Extracts import and require statements using transmission patterns
3. Cross-references found signal patterns against archival manifests
4. Reports orphaned artifacts, duplicate fragments, and corrupted transmissions
5. Purges from manifest (if --remove flag is used)

What it detects

✅ Detects

• import statements: import foo from 'bar'
• require() calls: require('foo')
• Scoped fragments: @babel/core
• Nested signal patterns: lodash/map → detects lodash
• Both dependencies and devDependencies manifests
• Duplicate artifacts across manifest sections
• Corrupted transmissions from NPM archival network

⚠️ Limitations

• Doesn't analyze dynamic imports like require(variable)
• Doesn't scan .json, .html, or configuration files
• Doesn't evaluate webpack/babel configuration networks
• Doesn't track indirect signal propagation

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests in watch mode
npm test:watch

# Run locally
node dist/cli.js

Contributing

Contributions welcome! Please feel free to submit a Pull Request to help maintain archival integrity across the network.

Field Notes

This tool was developed for maintaining clean archival nodes across signal networks. Each scan represents an integrity check of your project's dependency manifest against actual transmission patterns. Orphaned artifacts consume cache space and create noise in the signal. Regular purges maintain clarity and reduce corruption risk.

Signal integrity maintained • Archive Protocol

License

MIT © 2026