dirlens 1.0.19__tar.gz

dirlens-1.0.19/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: dirlens
+Version: 1.0.19
+Summary: Directory tree viewer with file sizes / ファイルサイズ付きディレクトリツリー表示ツール
+Author: igarin
+License: UNLICENSED
+Project-URL: Repository, https://github.com/igarinpiano/dirlens
+Keywords: cli,tree,file-size,directory,terminal
+Requires-Python: >=3.8

dirlens-1.0.19/README.md

@@ -0,0 +1,313 @@
+# dirlens 🌳
+
+ファイルサイズ付きのディレクトリツリーを表示するコマンドラインツール。  
+**Python 3.8+ のみで動作**（追加ライブラリ不要）。
+
+---
+
+## インストール
+
+### npm（推奨・全プラットフォーム共通）
+
+Node.js が入っていれば、どの OS でも同じコマンドでインストールできます。
+
+```bash
+npm install -g dirlens
+```
+
+インストール確認：
+
+```bash
+dirlens --help
+```
+
+アンインストール：
+
+```bash
+npm uninstall -g dirlens
+```
+
+---
+
+### macOS / Linux（スクリプト直接インストール）
+
+GitHubリポジトリから `dirlens.py` をダウンロードして使用します。
+
+```bash
+# /usr/local/bin にインストール（どこからでも呼べるようになる）
+sudo install -m 755 dirlens.py /usr/local/bin/dirlens
+
+# ── または sudo なしでユーザーローカルにインストール ──
+mkdir -p ~/.local/bin
+cp dirlens.py ~/.local/bin/dirlens
+chmod +x ~/.local/bin/dirlens
+
+# ~/.zshrc（zsh）または ~/.bashrc（bash）に以下を追記：
+export PATH="$HOME/.local/bin:$PATH"
+# 追記後に反映：
+source ~/.zshrc   # または source ~/.bashrc
+```
+
+インストール確認：
+
+```bash
+dirlens --help
+```
+
+---
+
+### Windows（スクリプト直接インストール）
+
+1. `dirlens.py` と `dirlens.bat` を任意のフォルダへ置く  
+   （例: `C:\Users\ユーザー名\bin\`）
+
+2. 同じフォルダに **`dirlens.bat`** を置く（同梱のものを使用）:
+
+   ```batch
+   @echo off
+   python "%~dp0dirlens.py" %*
+   ```
+
+3. そのフォルダを **システム環境変数 PATH** に追加：
+   - スタートメニュー →「環境変数を編集」→ PATH に追記
+   - または PowerShell（管理者）:
+
+     ```powershell
+     [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Users\ユーザー名\bin", "User")
+     ```
+
+4. 新しいターミナルを開いて確認：
+
+   ```cmd
+   dirlens --help
+   ```
+
+> **メモ**: Windows Terminal や VS Code のターミナルではカラー表示されます。  
+> 旧来のコマンドプロンプト（cmd.exe）ではカラーが出ない場合があります。
+
+---
+
+## 出力例
+
+```
+Desktop/ (2 dirs, 2 files, 3.74 MB)
+├── EmptyDir/ (0 dirs, 0 files, 0 bytes)
+├── Project/ (2 dirs, 1 file, 712 KB)
+│   ├── assets/ (1 dir, 0 files, 512 KB)
+│   │   └── images/ (0 dirs, 1 file, 512 KB)
+│   │       └── logo.png (512 KB)
+│   ├── src/ (0 dirs, 1 file, 80 KB)
+│   │   └── util.py (80 KB)
+│   └── main.py (120 KB)
+├── archive.zip (3 MB)
+└── readme.txt (50 KB)
+
+  合計  5 ディレクトリ,  5 ファイル
+  .py ×2  .txt ×1  .zip ×1  .png ×1
+```
+
+---
+
+## 特徴
+
+- **クロスプラットフォーム** — macOS / Linux / Windows
+- **tree コマンドとの高い互換性** — **`-a -d -f -g -l -p -u -r -s -t -c -L -D -P -I -n -J --prune --gitignore` など主要フラグが `tree` と互換**。dirlens 独自機能は `-G`（gitignore）・`-S`（サイズ順）・`-e`（拡張子）・`-C`（クリップボード）で提供
+- **カラー表示** — ディレクトリ・ファイル・シンボリックリンクを色で識別
+- **自動サイズ変換** — bytes / KB / MB / GB / TB
+- **ディレクトリサイズ** — サブディレクトリの合計サイズを自動計算（並列プリフェッチで高速化）
+- **アイテム数表示** — 各ディレクトリの直下にある dirs / files 数を表示
+- **拡張子統計** — ツリー全体のファイル種別を集計してサマリーに表示
+- **`.gitignore` 対応** — `-g` で除外（サブディレクトリも対応・否定パターン `!` 対応）
+- **最終更新日時** — `--date` / `-D` で相対表示
+- **拡張子フィルタ** — `-e py` など指定した拡張子のみ表示
+- **パターンフィルタ** — `--exclude` / `-I`、`--include` / `-P` でワイルドカード指定（複数可）
+- **サイズフィルタ** — `--min-size` / `--max-size` で容量による絞り込み
+- **空ディレクトリの剪定** — `--prune` でフィルタ後に空になる枝を非表示（tree --prune 互換）
+- **パーミッション表示** — `-p` でパーミッション文字列、`-u` で所有者名（tree -p/-u 互換）
+- **シンボリックリンク展開** — `-l` でリンク先を追跡、リンク先パスを `→` で表示
+- **フルパス表示** — `-f` でルートからのパスを表示（tree -f 互換）
+- **逆順ソート** — `-r` でソート順を逆転（tree -r 互換）
+- **ディスク占有率バー** — `--bar` で親ディレクトリに対する占有率を視覚表示
+- **絵文字アイコン** — `--emoji` で拡張子に応じた絵文字を付与
+- **Markdown出力** — `-m` でコードブロック形式に出力
+- **JSON出力** — `--json` / `-J` で機械可読な構造データを出力
+- **HTMLレポート** — `--html` でブラウザで閲覧できる折りたたみツリーを生成
+- **クリップボードコピー** — `-C` で出力を自動コピー（ANSIコードを自動除去）
+- **AIチャット貼り付けモード** — `--ai` 一発で gitignore除外・日時・Markdown・クリップボードコピーを全適用（人間がコピペする用）
+- **エージェント解析モード** — `--agent` 一発で下記のAI/エージェント向け解析機能を全適用（クリップボードは使わない、自律実行しても安全）
+- **隠しファイル対応** — `-a` で表示切り替え
+- **サイズ順ソート** — `-s` で大きいものから表示
+
+### AI/エージェント向け解析機能（`--agent` でまとめて有効化）
+
+これらはAIチャットやコーディングエージェントがプロジェクト構造を理解する際に、ファイルの中身を逐一読まなくても済むよう設計された機能です。個別フラグでも使えます。
+
+- **トークン数概算** — `-T` でファイルごとの推定トークン数を表示（英数字記号は約4文字/トークン、日本語等は約1.5文字/トークンとして概算）
+- **git連携** — `-H` で各ファイルの最終コミット情報（メッセージ・相対日時）を表示。直近2000コミットまで走査
+- **TODO/FIXME抽出** — `-K` で `TODO`/`FIXME`/`HACK`/`XXX` コメントを抽出し、行番号付きで一覧表示
+- **テスト欠落検知** — `-V` で対応するテストファイルが見つからないソースファイルをマーク（命名規則ベースのヒューリスティック）
+- **エントリーポイント検出** — `-N` で `main.py`・`index.js`・`package.json` の `main`/`bin` フィールドなどから入口ファイルを推測してマーク
+- **シンボルアウトライン** — `-O` で関数・クラス名を簡易抽出（Python/JS/TS/Go/Rust対応、正規表現ベースのbest-effort）
+- **import/依存グラフ** — `-M` でファイル間のローカルなimport関係を解析し、`imports×N`（依存先数）・`used-by×N`（被参照数）を表示。Pythonは標準ライブラリの`ast`で正確に解析、他言語は正規表現＋パス解決
+- **設定ファイル検出** — `-F` で `.env`・`tsconfig.json`・`Makefile` 等の設定ファイルを検出して一覧表示（既知のファイル名パターンのみ対応）
+
+---
+
+## 使い方
+
+```bash
+# ── AI チャットへの貼り付け（人間がコピペする用）──────────────
+dirlens --ai             # gitignore除外 + 日時 + Markdown + クリップボードコピー
+dirlens --ai -L 3        # 深さ指定と組み合わせ可
+
+# ── エージェント向け解析（自律実行向け・クリップボードは使わない）──
+dirlens --agent          # トークン数・git情報・TODO・テスト欠落・エントリーポイント・
+                          # アウトライン・import依存グラフ・設定ファイル一覧を一括表示
+dirlens --agent --json   # 同上をJSON形式で（スクリプト/エージェント連携向け）
+
+# ── AI/エージェント向け解析（個別フラグ）────────────────────────
+dirlens -T                # ファイルごとの推定トークン数
+dirlens -H                # 最終コミット情報（要git）
+dirlens -K                # TODO/FIXME/HACK/XXXを抽出
+dirlens -V                # テストが無いソースファイルを表示
+dirlens -N                # エントリーポイントらしきファイルをマーク
+dirlens -O                # 関数・クラスの簡易アウトライン
+dirlens -M                # ローカルなimport/依存関係を解析
+dirlens -F                # 設定ファイル（.env, tsconfig.json等）を検出して一覧表示
+
+# ── 表示制御 ──────────────────────────────────────────────────
+dirlens                  # カレントディレクトリ
+dirlens ~/Desktop        # 指定ディレクトリ
+dirlens -L 2             # 深さ2階層まで（tree -L 互換）
+dirlens -d               # ディレクトリのみ表示（tree -d 互換）
+dirlens -a               # 隠しファイルも表示
+dirlens -r               # 逆順ソート（tree -r 互換）
+dirlens --filesfirst     # ファイルをディレクトリより先に表示
+dirlens -f               # ルートからのフルパスで表示（tree -f 互換）
+
+# ── フィルタリング ────────────────────────────────────────────
+dirlens -G               # .gitignore のファイルを除外
+dirlens -G --prune       # gitignore除外 + 空になった枝を剪定
+dirlens -e py            # .py のみ表示
+dirlens -P '*.md'        # .md のみ表示（tree -P 互換）
+dirlens -I '*.log'       # .log を除外（tree -I 互換）
+dirlens --exclude 'dist' --exclude '*.log'   # 複数除外
+dirlens --min-size 1M    # 1MB 以上のファイルのみ
+dirlens --max-size 100K  # 100KB 以下のファイルのみ
+
+# ── ソート ────────────────────────────────────────────────────
+dirlens -S               # サイズの大きい順に表示
+dirlens -t               # 更新日時順にソート（新しい順・tree -t 互換）
+dirlens -c               # ステータス変更日時順にソート（tree -c 互換）
+dirlens -t -r            # 更新日時順・古い順
+
+# ── 詳細情報 ──────────────────────────────────────────────────
+dirlens --date           # 最終更新日時を相対表示（tree -D 互換は -D）
+dirlens -D               # 同上（tree -D 互換）
+dirlens --bar            # ディスク占有率バーを表示
+dirlens --emoji          # 絵文字アイコンを表示
+dirlens -p               # パーミッションを表示（tree -p 互換）
+dirlens -u               # 所有者名を表示（tree -u 互換）
+dirlens -g               # グループ名を表示（tree -g 互換）
+dirlens -p -u -g         # 全部表示
+dirlens -l               # シンボリックリンク先を展開（tree -l 互換）
+
+# ── 出力形式 ──────────────────────────────────────────────────
+dirlens -m               # Markdown コードブロック形式で出力
+dirlens --json           # JSON 形式（tree -J 互換は -J）
+dirlens --html           # HTML レポートを生成（デフォルト: dirlens.html）
+dirlens -C               # クリップボードにコピー
+dirlens --no-color       # カラーなし（tree -n 互換は -n）
+dirlens --no-color > dirlens.txt   # テキストファイルに書き出す
+```
+
+---
+
+## オプション一覧
+
+| オプション           | 省略形        | 説明                                                        |
+|---------------------|--------------|-------------------------------------------------------------|
+| `path`              | —            | 対象ディレクトリ（省略時はカレント）                           |
+| **`--ai`**          | —            | **`-G --date -m -C` のショートカット。人間がAIチャットに貼り付ける用** |
+| **`--agent`**       | —            | **`-G --date -T -H -K -V -N -O -M -F` のショートカット。エージェント向け解析（クリップボードは使わない）** |
+| `--depth N`         | `-L N`       | 表示する最大の深さ                                            |
+| `--all`             | `-a`         | 隠しファイル・ディレクトリも表示                               |
+| `-d`                | —            | ディレクトリのみ表示                                          |
+| `--sort-size`       | `-S`         | サイズが大きい順に並べる                                       |
+| `-s`                | —            | サイズ表示（tree互換・常時表示されているため実質no-op）        |
+| `-t`                | —            | 更新日時順にソート（新しい順）                                 |
+| `-c`                | —            | ステータス変更日時順にソート                                   |
+| `--reverse`         | `-r`         | ソート順を逆にする                                            |
+| `--filesfirst`      | —            | ファイルをディレクトリより先に表示                              |
+| `--gitignore`       | `-G`         | `.gitignore` に記載されたファイルを除外（サブディレクトリも対応）|
+| `--prune`           | —            | フィルタ後に空になるディレクトリを非表示                       |
+| `--date`            | `-D`         | 最終更新日時を相対表示                                        |
+| `--perms`           | `-p`         | パーミッション文字列を表示                                     |
+| `--user`            | `-u`         | 所有者のユーザー名を表示                                      |
+| `-g`                | —            | グループ名を表示                                              |
+| `--follow`          | `-l`         | シンボリックリンク先ディレクトリを展開（循環検出あり）           |
+| `--full-path`       | `-f`         | ルートからのフルパスで表示                                     |
+| `--type EXT`        | `-e EXT`     | 指定した拡張子のファイルのみ表示（例: `-e py`）                |
+| `--include PATTERN` | `-P PATTERN` | このパターンのみ表示（複数指定可）                              |
+| `--exclude PATTERN` | `-I PATTERN` | 除外パターン（複数指定可）                                     |
+| `--min-size SIZE`   | —            | 指定サイズ以上のファイルのみ表示（例: `1M`, `500K`）           |
+| `--max-size SIZE`   | —            | 指定サイズ以下のファイルのみ表示                               |
+| `--bar`             | —            | ディスク占有率バーを表示                                       |
+| `--emoji`           | —            | 拡張子に応じた絵文字アイコンを表示                             |
+| `--tokens`          | `-T`         | ファイルごとの推定トークン数を表示（概算）                      |
+| `--git`             | `-H`         | 最終コミット情報を表示（要git、直近2000コミットまで走査）        |
+| `--todo`            | `-K`         | TODO/FIXME/HACK/XXXコメントを抽出                             |
+| `--missing-tests`   | `-V`         | 対応するテストファイルが見つからないソースファイルを表示          |
+| `--entry`           | `-N`         | エントリーポイントらしきファイルを検出してマーク                 |
+| `--outline`         | `-O`         | 関数・クラスの簡易アウトラインを表示（正規表現ベース・対応言語限定）|
+| `--imports`         | `-M`         | ローカルなimport/依存関係を解析して表示（外部パッケージは対象外） |
+| `--config`          | `-F`         | 設定ファイル（.env, tsconfig.json, Makefile等）を検出して一覧表示（既知のファイル名パターンのみ） |
+| `--markdown`        | `-m`         | Markdown コードブロック形式で出力（カラー自動無効）             |
+| `--json`            | `-J`         | JSON 形式で標準出力に出力                                     |
+| `--html [FILE]`     | —            | HTML レポートを生成（デフォルト: `dirlens.html`）              |
+| `--copy`            | `-C`         | 出力をクリップボードにコピー（ANSIコードを自動除去）            |
+| `--no-color`        | `-n`         | カラー表示を無効化                                            |
+
+---
+
+## カラーの意味
+
+| 表示色         | 意味                   |
+|---------------|------------------------|
+| 青（太字）     | ルートディレクトリ       |
+| シアン（太字） | サブディレクトリ         |
+| 緑            | ファイル                |
+| マゼンタ       | シンボリックリンク       |
+| 暗色（dim）   | サイズ表示              |
+
+---
+
+## 仕様・注意事項
+
+- ディレクトリのサイズは **全サブファイルの合計**（隠しファイルを含む、`.gitignore` 対象も含む）
+- ディレクトリサイズはルート直下を **並列プリフェッチ** して高速化（透過的な最適化）
+- **`+` 表記** — 一部のサブディレクトリが読めなかった場合、サイズは `1.5+ KB`（少なくとも 1.5 KB）、件数は `3+ dirs` のように表示。個々のファイルサイズは親ディレクトリのスキャン時に取得できるので `+` なし（正確な値）
+- **アクセス拒否** — 読めないディレクトリは赤太字で `[アクセス拒否]` を表示してスキップ。そのディレクトリは `0+ dirs, 0+ files, 0+ bytes` として表示される
+- **シンボリックリンク** は `→ リンク先パス` で表示。`-l` でリンク先ディレクトリを展開（循環検出あり）
+- 非常に深いディレクトリ（1万階層以上）は `-L` で深さを制限してください
+- **ホームフォルダ（`~/`）やルート（`/`）で実行すると固まる場合があります** — サイズ計算は表示深さに関わらず底まで全再帰するため、`~/Library` や iCloud Drive など大容量ディレクトリで時間がかかります
+- **`-G` の否定パターン（`!`）** は対応していますが、ディレクトリを除外した後にその中のファイルを `!` で復活させることは非対応です（`*.log` + `!important.log` のようなファイル単位の否定は動作します）
+- `-p`（パーミッション）・`-u`（ユーザー名）・`-g`（グループ名）は macOS / Linux のみ対応（Windows では ID 番号を表示）
+
+### AI/エージェント向け解析機能の精度について
+
+dirlens は外部ライブラリに依存しない方針で作られているため、以下の機能は**完全な精度を保証しません**。重要な判断の根拠にする場合は、該当ファイルの中身を直接確認することを推奨します。
+
+| 機能 | 制限事項 |
+|---|---|
+| トークン数概算（`-T`） | 文字数ベースの大まかな目安。実際のトークナイザーとは一致しない |
+| シンボルアウトライン（`-O`/`-A`） | 正規表現ベースの簡易抽出（ASTではない）。デコレータが複雑な場合や複数行にまたがる関数シグネチャは取得漏れすることがある。対応言語は Python・JS/TS・Go・Rust のみ |
+| import/依存グラフ（`-M`） | Pythonは標準ライブラリの `ast` で正確に解析されるため信頼度が高い。JS/TS/Go/Rustは正規表現＋パス解決のため、JS/TSのbare import（`react`等）・Rustの`self::`/`super::`・外部crate・モジュール外のGoパッケージは解決されず「external」扱いになる |
+| テスト欠落検知（`-V`） | ファイル命名規則のみで判定（`test_foo.py`等）。実際のテストカバレッジは見ていない。Rustは対象外（インラインテストの慣習のため検出不可） |
+| エントリーポイント検出（`-N`） | 既知のファイル名パターンと `package.json` の `main`/`bin` フィールドのみで判定 |
+| TODO/FIXME抽出（`-K`） | 単純な文字列マッチ。コメント外の文字列内に偶然該当語があっても拾われる場合がある |
+| git連携（`-H`） | 直近2000コミットのみ走査。それより古い変更しかないファイルは情報が出ない |
+
+### AIエージェントへの指示テンプレート
+
+エージェント（Claude Code・Cursor等）にプロジェクト探索の手順として `dirlens --agent` を使わせたい場合、`AGENT_RULE.md` のテンプレートを `CLAUDE.md`・`.cursorrules` 等のグローバルルールファイルにそのまま貼り付けて使えます。

dirlens-1.0.19/dirlens.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: dirlens
+Version: 1.0.19
+Summary: Directory tree viewer with file sizes / ファイルサイズ付きディレクトリツリー表示ツール
+Author: igarin
+License: UNLICENSED
+Project-URL: Repository, https://github.com/igarinpiano/dirlens
+Keywords: cli,tree,file-size,directory,terminal
+Requires-Python: >=3.8

dirlens-1.0.19/dirlens.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+dirlens.py
+pyproject.toml
+dirlens.egg-info/PKG-INFO
+dirlens.egg-info/SOURCES.txt
+dirlens.egg-info/dependency_links.txt
+dirlens.egg-info/entry_points.txt
+dirlens.egg-info/top_level.txt

dirlens-1.0.19/dirlens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dirlens-1.0.19/dirlens.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dirlens = dirlens:main

dirlens-1.0.19/dirlens.egg-info/top_level.txt

@@ -0,0 +1 @@
+dirlens