uniquity-reporter

v1.4.4

Published

7 months ago

UniquityReporter is a system that verifies whether a software project is a reinvention of the wheel and provides a comparative analysis with existing similar solutions.

0High
0Medium
0Low

kunihiros

UniquityReporter

UniquityReporter is a system that verifies whether a software project is a "reinvention of the wheel" and provides a comparative analysis with existing similar solutions. Output is available in both English and Japanese.

MCP Server

UniquityReporter can be used from MCP Server. MCP Server repository will be public available. (currently private)

Version History

1.4.0:

Added --model option
Added --log and --logfile options
Updated required libraries

1.3.0:

Made compatible with MCP Server calls

1.2.0:

Changed command line interface
Updated translation model from 4o-mini to 4.1-nano

1.1.1:

Added English language support to output reports
Implemented translation mechanism that first creates English version, then translates to other languages using gpt-4o-mini

Output Streams and Formats

1. Report Output

Destination:
- Standard output (when --repo=off or not specified)
- Specified file (when --repo=on --repofile=<path>)
Format: Markdown text
Note:
- When --repo=on is specified, --repofile is required
- --repofile should be a full file path where the report will be saved
- If the directory doesn't exist, it will be created automatically
- Example paths:
  - ./reports/analysis.md (relative path)
  - /home/user/reports/analysis.md (absolute path)

2. Log Output

Destination:
- Standard error (when --log or --log=on is specified without --logfile)
- Specified file (when --logfile=<path> is provided)
Format: Plain text with timestamp and log level
Security:
- Automatically masks sensitive information using entropy analysis and pattern matching
- Detects and masks API keys, tokens, passwords, and other credentials

Example:

[2025-05-18T14:15:19.000Z] INFO: Processing repository https://github.com/owner/repo
[2025-05-18T14:15:20.000Z] WARN: Using default configuration
[2025-05-18T14:15:21.000Z] ERROR: Failed to connect to API (attempt 1/3)

Command Line Options

Basic Options

| Option | Required | Default | Description | |--------|----------|---------|-------------| | <repository URL> | Yes | - | Target GitHub repository URL | | --repo=<on/off> | No | off | Control report output destination. When on, requires --repofile. | | --repofile=<path> | Required when --repo=on | - | Full output file path for report. The directory will be created if it doesn't exist. | | --model=<model> | No | Value from .env or config/config.js | OpenAI model to use | | --log=<on/off> | No | off | Enable/disable verbose logging (--log=on to enable, --log=off to disable) | | --logfile=<path> | No | - | Full output file path for logs (including filename, default: stderr) |

Option Details

`--repo=<on/off>`

| Value | Description | |-------|-------------| | --repo=on | Save report to file specified by --repofile | | --repo=off or not specified | Display report on standard output (default) |

`--repofile=<path>`

| Value | Description | |-------|-------------| | Path | Full path where the report will be saved. The directory will be created if it doesn't exist. | | | Required when --repo=on is specified | | | Example: --repofile=./reports/analysis.md |

`--log=<on/off>`

| Value | Description | |-------|-------------| | --log=on | Enable verbose logging | | --log=off or not specified | Only log errors (default) |

`--logfile=<path>`

| Value | Description | |-------|-------------| | Path | Full path where logs will be saved. The directory will be created if it doesn't exist. | | | When not specified, logs are written to stderr | | | Example: --logfile=./logs/debug.log |

NPX Cache Management

When using npx to run UniquityReporter, please be aware of the following cache behavior:

Cache Behavior

NPX caches packages to improve performance
The cache is persistent and doesn't expire automatically
Cached versions are stored in:
- macOS/Linux: ~/.npm/_npx
- Windows: %APPDATA%\npm-cache\_npx

Running Specific Versions

# Always use the latest version
npx uniquity-reporter@latest <github-url>

# Use a specific version
npx [email protected] <github-url>

Clearing NPX Cache

To clear the entire NPX cache:

npx clear-npx-cache

To clear a specific package's cache, you'll need to manually remove it from the cache directory.

Usage Examples

Basic Commands

Run with default settings (report to stdout):

npx uniquity-reporter https://github.com/username/repository

Force update to latest version (bypass cache):

npx uniquity-reporter@latest https://github.com/username/repository

Run specific version:

npx [email protected] https://github.com/username/repository

Advanced Usage

Save Report to File (no logs):

# Directory will be created automatically if it doesn't exist
npx uniquity-reporter --repo=on --repofile=./reports/analysis.md https://github.com/username/repository

Enable Logging (text output to stderr, log level info):

npx uniquity-reporter --log=on https://github.com/username/repository

Enable Debug Logging (output to file):

# Create logs directory first if it doesn't exist
mkdir -p ./logs
   
# Run with full log file path
npx uniquity-reporter --log=on --logfile=./logs/debug.log https://github.com/username/repository

Save Report and Logs to Files:

# Directories will be created automatically if they don't exist
npx uniquity-reporter \
  --repo=on \
  --repofile=./reports/analysis_$(date +%Y%m%d_%H%M%S).md \
  --log=on \
  --logfile=./logs/analysis_$(date +%Y%m%d_%H%M%S).log \
  https://github.com/username/repository

Note: The tool will not create directories automatically. Make sure the target directories exist before running the command.

Important Notes

Directory Creation:
- Output directories for reports and logs are created automatically if they don't exist
- You don't need to create directories manually
File Paths:
- Both absolute and relative paths are accepted
- Existing files will be overwritten
Environment Variables:
- .env file configuration is required
- Copy .env.example to create your .env file
Other:
- Repository URL must be a valid GitHub repository
- Set up required API keys in .env before running
- On first run, create .env by copying .env.example and configure your API keys

Security Features not implemented yet

Sensitive Data Protection

All logs are automatically scanned for sensitive information:

Pattern Matching:
- Field names containing: password, token, api[_-]?key, secret, auth, credential, etc.
- Common formats: API keys, OAuth tokens, JWT tokens, etc.
Entropy Analysis:
- Detects high-entropy strings that might be cryptographic material
- Ignores common false positives (UUIDs, hashes, etc.)
Automatic Masking:
- Detected sensitive values are replaced with ***MASKED***
- Original values are never written to logs

Example of Protected Data

[2025-05-18T14:15:19.000Z] INFO: Processing repository
[2025-05-18T14:15:20.000Z] DEBUG: Using config: {
  "apiKey": "***MASKED***",
  "database": {
    "host": "db.example.com",
    "password": "***MASKED***"
  }
}
[2025-05-18T14:15:21.000Z] ERROR: Failed to connect to database

Architecture

System Flow

sequenceDiagram
    participant User
    participant CLI as UniquityReporter CLI
    participant Git
    participant OpenAI
    participant Tavily

    User->>CLI: Execute with Repository URL
    CLI->>Git: Fetch Repository Info
    Git-->>CLI: Return Metadata

    CLI->>OpenAI: Generate Search Query
    OpenAI-->>CLI: Optimized Query

    CLI->>Tavily: Search Similar Projects
    Tavily-->>CLI: Search Results

    loop For High-Scoring Results
        CLI->>Tavily: Extract Content Details
        Tavily-->>CLI: Detailed Content
    end

    CLI->>OpenAI: Generate Report
    OpenAI-->>CLI: Analysis Report

    CLI-->>User: Display Report

Core Components

flowchart TB
    subgraph CLI["UniquityReporter CLI"]
        direction TB
        Controller["Main Controller<br>- CLI Argument Parsing<br>- Process Control"]
        GitAnalyzer["Repository Analyzer<br>- Git Analysis<br>- Metadata Extraction"]
        QueryGen["Query Generator<br>- OpenAI Integration<br>- Context Optimization"]
        Search["Search Service<br>- Tavily Search<br>- Result Filtering"]
        ReportGen["Report Generator<br>- Analysis<br>- Markdown Formatting"]
        Logger["Logger<br>- Structured Logging<br>- Level Control"]

        Controller --> GitAnalyzer
        Controller --> Logger
        GitAnalyzer --> QueryGen
        QueryGen --> Search
        Search --> ReportGen
        ReportGen --> Controller
    end

    subgraph ExternalServices["External Services"]
        GitHub["GitHub API"]
        OpenAI["OpenAI API"]
        TavilyS["Tavily Search API"]
        TavilyE["Tavily Extract API"]
    end

    GitAnalyzer --> GitHub
    QueryGen --> OpenAI
    Search --> TavilyS
    Search --> TavilyE
    ReportGen --> OpenAI

For Developers

Configuration Management

All configuration values, API keys, and parameters must be obtained through config/config.js
Direct access to process.env or .env files in the application code is prohibited
This approach ensures:
- Centralized configuration management
- Improved security
- Easier testing and mocking

License

MIT License - See the LICENSE file for details.