Examples

Common use cases and examples for using Unreach.

Basic Usage

Scan TypeScript Project

unreach scan /path/to/typescript-project

Scan with Custom Entry Point

unreach scan --entry src/main.ts

Scan with Multiple Entry Points

unreach scan --entry src/index.ts,src/cli.ts

Exporting Results

Export as JSON for Automation

# Explicit format
unreach scan --export json

# Or use default (JSON) by omitting the format
unreach scan --export

This creates a {scanned-directory}/reports/unreach-report.json file that can be used in CI/CD pipelines or other automation tools.

Note: The reports/ directory is created relative to the scanned directory, not the current working directory.

Export in Multiple Formats

unreach scan --export json,html,md

This creates three files in the {scanned-directory}/reports/ directory:

• reports/unreach-report.json
• reports/unreach-report.html
• reports/unreach-report.md

Export to Custom Directory

unreach scan --export json --export-path ./custom-reports

Keep History with Timestamps

unreach scan --export json --history

This creates files with timestamps:

• reports/unreach-report-2024-01-15T14-30-45.json
• reports/unreach-report-2024-01-16T09-20-10.json

Useful for tracking changes over time.

CI/CD Integration

GitHub Actions Example

name: Find Unused Code

on:
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npx unreach@latest scan --export json
      - uses: actions/upload-artifact@v3
        with:
          name: unreach-report
          path: reports/unreach-report.json

GitLab CI Example

find-unused-code:
  image: node:18
  script:
    - npx unreach@latest scan --export json
  artifacts:
    paths:
      - reports/unreach-report.json

Quiet Mode

Suppress all output except errors (useful for scripts):

unreach scan --quiet

Disable Progress Bar

For non-interactive environments:

unreach scan --no-progress

Working with Monorepos

Scan Specific Package

unreach scan packages/my-package

Scan with Multiple Entry Points

unreach scan --entry packages/app/src/index.ts,packages/cli/src/index.ts

Watch Mode

Continuously monitor files and automatically re-scan on changes:

unreach scan --watch

Watch mode includes:

• Automatic re-scanning on file changes
• Rate limiting to prevent excessive scans (configurable via watchRateLimit in config, default: 1 scan/second)
• Debounced file change detection
• Support for all scan options
• Graceful shutdown on SIGINT (Ctrl+C) or SIGTERM

To stop watching, press Ctrl+C.

Interactive Mode

Menu-driven interface for configuring scans:

unreach scan --interactive

The interactive menu guides you through:

• Directory selection
• Entry point configuration
• Export format selection
• Output grouping preferences
• Visualization options
• Benchmark settings

Advanced Options

Verbose Mode

Get detailed file-by-file processing information:

unreach scan --verbose

Debug Mode

Enable stack traces and detailed error information:

unreach scan --debug

Benchmark Mode

Track and display performance metrics:

unreach scan --benchmark

Shows:

• Parse time
• Analysis time
• Memory usage
• Total execution time

Summary Statistics

Display detailed summary statistics about the scan:

unreach scan --stats

Shows:

• Files analyzed count
• Packages analyzed count
• Entry points count
• Unused items breakdown by category
• Total unused items count

Dependency Visualization

Generate an interactive HTML dependency graph:

unreach scan --visualize

Creates dependency-graph.html with an interactive visualization.

Grouped Output

Group results by type (default) or by file:

# Group by type (default)
unreach scan --group-by type

# Group by file
unreach scan --group-by file

Incremental Analysis

Unreach caches analysis results for faster subsequent scans. To disable:

unreach scan --no-incremental

Configuration Files

Use --no-config to ignore configuration files:

unreach scan --no-config

Integration with Other Tools

Combine with Other Tools

# Run Unreach and save results
unreach scan --export json > results.json

# Process results with jq
cat results.json | jq '.unusedPackages[] | .name'

Generate HTML Report for Sharing

unreach scan --export html
# Open reports/unreach-report.html in browser