Metadata-Version: 2.4
Name: mper
Version: 1.1.1
Summary: Discord bot permission scanner - Analyzes discord.py code to detect required permissions and generate invite links
Author-email: FreeWiFiTech <wifi@freewifitech.jp>
Maintainer-email: FreeWiFi7749 <wifi@freewifitech.jp>
License: MIT License
        
        Copyright (c) 2024 easy-make-invite-url-for-discord-bot
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/FreeWiFi7749/mper.py
Project-URL: Repository, https://github.com/FreeWiFi7749/mper.py
Project-URL: Issues, https://github.com/FreeWiFi7749/mper.py/issues
Keywords: discord,discord.py,bot,permissions,invite,scanner,ast,code-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# mper

[![PyPI version](https://badge.fury.io/py/mper.svg)](https://badge.fury.io/py/mper)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Discord Bot Permission Scanner** - discord.pyのコードを解析し、必要なパーミッションを検出して招待リンクを生成するツール。

## 特徴

| 機能 | 説明 |
|------|------|
| **メソッドベース検出** | `.ban()`, `.kick()`, `.send()` などのメソッド呼び出しからBotパーミッションを自動推測 |
| **証拠トラッキング** | どのファイルの何行目でどのパーミッションが必要かを表示 |
| **全49パーミッション対応** | Discord APIの全パーミッションをサポート |
| **コンテキスト認識** | `member.edit(nick=...)` と `member.edit(mute=...)` を区別 |
| **デコレータサポート** | `@bot_has_permissions`（補助）、`@has_permissions`（ユーザー要件のみ） |
| **アップデート通知** | 新しいバージョンがリリースされた際にCLIで通知 |

## インストール

```bash
pip install mper
```

## 使い方

### CLI

```bash
# 基本的な使い方
mper /path/to/bot/directory CLIENT_ID

# 詳細レポート付き
mper /path/to/bot/directory CLIENT_ID --report

# 詳細出力
mper /path/to/bot/directory CLIENT_ID --verbose

# ディレクトリを除外
mper /path/to/bot/directory CLIENT_ID --exclude tests docs

# カスタムOAuth2スコープ
mper /path/to/bot/directory CLIENT_ID --scope bot --scope applications.commands

# プレーンテキスト出力（色なし）
mper /path/to/bot/directory CLIENT_ID --plain
```

### CLIオプション

| オプション | 説明 |
|------------|------|
| `--report` | 証拠付きの詳細パーミッションレポートを表示 |
| `--verbose`, `-v` | スキャン中の詳細出力を表示 |
| `--no-inferred` | デコレータからの宣言パーミッションのみ使用 |
| `--exclude` | 除外するディレクトリを追加 |
| `--scope` | 招待リンクのOAuth2スコープ（デフォルト: bot, applications.commands） |
| `--output`, `-o` | 招待リンクの出力ファイル（デフォルト: bot_invite_url.txt） |
| `--no-color` | 色付き出力を無効化 |
| `--plain` | プレーンテキスト出力（スタイルなし） |

### ライブラリとして使用

```python
import mper

# 簡単に招待URLを生成（CLIと同じ動作）
url = mper.generate_invite_url("./my_bot", client_id="123456789012345678")
print(url)

# 詳細なスキャン結果を取得
result = mper.scan_directory("./my_bot")
print(f"検出されたパーミッション: {result['invite_link_permissions']}")

# パーミッション名から整数値を計算
perm_int = mper.calculate_permission_integer({'send_messages', 'ban_members'})

# カスタム招待URLを作成
url = mper.create_invite_link(
    client_id="123456789012345678",
    permissions=perm_int,
    scopes=['bot', 'applications.commands']
)
```

詳細な使用例は [examples/](examples/) を参照してください。

### 出力例

```
╭──────────────────────────────────────────────────╮
│  mper - Discord Bot Permission Scanner           │
╰──────────────────────────────────────────────────╯

Scanning: /path/to/bot
Scanned 5 files (0 with errors)

┌─────────────────────────────────────────────────┐
│ Detected Permissions (from method calls)        │
├─────────────────┬───────────┬───────────────────┤
│ Permission      │ Bit Value │ Evidence          │
├─────────────────┼───────────┼───────────────────┤
│ ban_members     │ 0x4       │ bot.py:15         │
│ manage_messages │ 0x2000    │ bot.py:25         │
│ send_messages   │ 0x800     │ bot.py:10, 20, 30 │
└─────────────────┴───────────┴───────────────────┘

╔══════════════════════════════════════════════════╗
║ 🔗 INVITE LINK                                   ║
╠══════════════════════════════════════════════════╣
║ https://discord.com/oauth2/authorize?...         ║
╚══════════════════════════════════════════════════╝
```

## 仕組み

```
┌─────────────────────────────────────────────────────────────┐
│                    mper スキャンプロセス                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. メソッドベース検出 (PRIMARY)                              │
│     Python AST解析 → discord.pyメソッド検出 → パーミッション推測 │
│     例: member.ban() → ban_members                          │
│                                                             │
│  2. @bot_has_permissions (SUPPLEMENTARY)                    │
│     明示的なBot権限宣言 → 招待リンクに追加                     │
│                                                             │
│  3. @has_permissions (REFERENCE ONLY)                       │
│     ユーザー権限要件 → レポートに表示のみ（招待リンクには不含）  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 対応パーミッション

Discord APIの全49パーミッション（ビット0-46, 49-50）に対応しています。

詳細は [Discord API Documentation](https://discord.com/developers/docs/topics/permissions) を参照してください。

## ライセンス

MIT License - 詳細は [LICENSE](LICENSE) を参照してください。

## Issues

問題や要望がある場合は、適切なタグを付けてIssueを作成してください：

| タグ | 用途 |
|------|------|
| `bug` | バグ報告 |
| `enhancement` | 機能要望 |
| `question` | 質問 |

## クレジット

- 開発者: [@FreeWiFi7749](https://github.com/FreeWiFi7749)
