Skip to content

About

No description or website provided.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

folder-tree-excel

公開名義の移行に伴い、このリポジトリはソースコードのみを公開しています。新しい .xlsm・tag・Release は未配布です。旧 v1.1.1 の配布物はこのソースから再検証した成果物ではなく、このリポジトリでは再公開しません。配布物の再生成と Excel 実機での検証は別途行います。

指定したフォルダの階層を読み取り、Excel のアウトライン機能で折りたためるツリー一覧として出力するマクロ有効ブック(.xlsm)。走査結果を専用シートへ複製し、内容を確認してから明示的に実行するファイル操作(名前変更・移動・新規フォルダ作成・ファイル/空フォルダのゴミ箱への移動)にも対応する。

candidate-only build、VBA compile、再オープン、5 moduleのembedded hash、必須ケース1〜68、候補拘束性能ゲートを満たしたcandidateだけを配布物へ昇格する。実Recycle Bin fixtureの照合・復元、UNC fail-closed、local volume/policy判定も検証済み。

通常利用では、VBA sourceやPowerShellは不要。Windowsデスクトップ版Excel、マクロ有効化、署名なしが前提。

現行ソースには未リリースの安全性修正が含まれます。過去の実機測定値は修正後の動作保証ではありません。 配布候補の生成前に、Windowsデスクトップ版Excelで拡張した必須ケースと性能ゲートを再実行してください。

概要

指定したフォルダを読み取り専用の一覧として確認し、利用者が明示的に承認した操作だけを実行する、Windowsデスクトップ版Excel向けのツールです。

動作要件

項目 内容
OS Windows(デスクトップ版 Excel が動作する環境)
Excel デスクトップ版 Excel(Microsoft 365 等。Excel Online 不可)
実機確認済み組合せ Windows on ARM(64-bit ARM)+ Excel 16.0 build 20228

VBA ソースは 32-bit/64-bit 双方の API 宣言(#If VBA7)に対応するよう書かれていますが、上記以外の Windows/Excel バージョンや bitness の組合せでの動作は実機確認していません。未検証の環境では自己責任で利用し、不具合があれば Issue で報告してください。

インストール

以下は今後、検証済みの配布物を公開した場合の手順です。現在このリポジトリからダウンロードできる .xlsm はありません。

  1. 配布が開始された後、該当 Release から folder-tree-excel-vX.Y.Z.xlsm、SHA256SUMS.txt をダウンロードします。

  2. ダウンロードしたファイルの SHA-256 を計算し、SHA256SUMS.txt の値と一致することを確認します。

    Get-FileHash .\folder-tree-excel-vX.Y.Z.xlsm -Algorithm SHA256
  3. 配布物は署名していません(unsigned)。発行者の同一性はハッシュ値の一致だけでは保証されないため、src/ のソースコードと照らし合わせて内容を確認することを推奨します。

初回起動時の注意

インターネット経由でダウンロードしたファイルには Mark of the Web が付与され、Excel は既定でマクロをブロックします。

  • ハッシュ値とソースを確認して信頼できると判断した場合だけ、ファイルを右クリック → プロパティ → 下部の 許可する にチェック → OK の順で Unblock してください。
  • 「セキュリティセンター」で「すべてのマクロを有効にする」を選択したり、インターネット全体を信頼済みサイトに追加したり、広い範囲を信頼済みの場所(Trusted Location)に登録したりしないでください。 個別ファイルの Unblock だけで十分です。
  • 通常の利用者は AccessVBOM(VBA プロジェクト オブジェクト モデルへのアクセス)を有効にする必要はありません。この設定はビルド・テストを行う開発者だけが必要とします。

安全に使うために

  • 初めて使う際は、バックアップを取った上でテスト用のフォルダに対して試してください。
  • ファイル操作(ゴミ箱への移動)はゴミ箱の容量・グループポリシー・組織のポリシーの影響を受けます。ゴミ箱を使えない状態では操作を拒否し、完全削除へフォールバックしません。
  • ツリー シートや 実行ログ シートには走査対象フォルダの絶対パスがそのまま記録されます。使用済みのブックファイルを第三者と共有したり、そのまま Issue に添付したりしないでください。
  • このツールは外部ネットワークへ通信しません。詳細は SECURITY-MODEL.md を参照してください。

サポート・セキュリティ・ライセンス

ライセンス

このプロジェクトは MIT License の下で公開します。

アンインストール

インストーラーや常駐サービスはありません。不要になった場合は、ダウンロードした .xlsm と、必要に応じてcloneしたsource directoryを削除してください。Excelの設定やレジストリを変更する必要はありません。

成果物

ファイル 内容
src/modFolderTree.bas VBA ソース(UTF-8。ビルド時に cp932 へ変換して取り込む)
src/modOperationPlan.bas 操作案、検査、fingerprint
src/modFileOperations.bas rename/move/mkdir、journal、rollback
src/modRecycleBin.bas ゴミ箱移動だけを公開するShell API境界
src/modWorkbookIo.bas 変更操作/実行ログ、Value2 I/O、保護
scripts/build-xlsm.ps1 .xlsm を組み立て直す生成スクリプト
scripts/test-xlsm.ps1 既知のフォルダ構成に対してマクロを実行する検証スクリプト

使用方法

  1. 配布された .xlsm を開き、コンテンツの有効化(マクロの有効化)を許可する。
  2. 設定 シートで [1. フォルダを選択] を押し、読み取り対象のフォルダを指定する。
  3. 必要に応じてオプションを変更する。
  4. [2. ツリーを作成] を押すと ツリー シートへ結果が出力される。
  5. ツリー シート左端の + / -、または行番号の上に出る 1〜8 の数字ボタンで階層を折りたためる。 設定 シートの [すべて展開] / [2 階層まで折りたたむ] でも一括操作できる。

ファイル操作

  1. 2. ツリーを作成 を正常完了させ、3. 変更一覧を作成 を押します。
  2. 変更操作 シートで、編集可能な 操作種別、新しい名前、移動先相対フォルダ、 新規フォルダ相対パス だけを入力します。
  3. 必要なら 連番を設定 でpreviewを作成します。報告書.pdf は先頭なら 00_報告書.pdf、 末尾なら 報告書_00.pdf になります。100件では自動的に 000 形式へ拡張します。
  4. 事前確認 の結果と代表destinationを確認し、明示的に 変更を実行 を押します。

一覧生成は最大100,000行、1 batchの実操作は最大10,000件です。これは別々の制約です。 一覧が100,000行を超えた場合は一部一覧を作成せず、操作対象サブフォルダを新しい走査rootとして 設定!C5 に指定して再走査してください。batch上限を超える場合もrootまたは操作案を分割します。

セル編集、一覧作成、連番previewだけでは実ファイルを変更しません。走査root、sourceの実在性、 reparse、禁止名、collision、stale状態、編集列formulaを実行前に再検査します。plan fingerprintと 走査完了状態はメモリだけに保持され、ブック再オープン、VBA state reset、未処理エラー後は再走査・ 一覧再作成・事前確認が必要です。

ソース上は、ファイル名変更、走査root内のファイル移動、新規フォルダ作成、ファイル/空フォルダの ゴミ箱移動だけを許可します。フォルダの名前変更・移動、非空フォルダ、root外、上書き、完全削除、 新規ファイル作成は拒否します。削除境界には固定local volume、volume GUID、NukeOnDelete、 MaxCapacity/RecycleBinSize、安全margin、phase前後snapshot、元path・種別・size・mtime照合、 既存項目保持と外部混入検出を実装しています。必須ケース41/42/67/68でworkspace内fixtureを 実ゴミ箱へ移動し、照合後に元場所へ復元する検証を完了しています。既存使用量・バッチ合計・安全marginが容量を超える場合は実行前に拒否します。外部操作や設定変更との競合まで保持を保証するものではありません。

名前変更・移動・新規フォルダ作成は、成功したWin32操作を順序付きjournalへ記録し、削除開始前の失敗時に逆順rollbackを試みます。A/B交換の一時退避と再帰作成した親フォルダも対象です。復元時にはfile identityと必要な属性を照合します。ゴミ箱移動後の自動復元は 保証しないため、削除開始後の結果はatomic successとは表示しません。実行ログ はappend-onlyで、成功・失敗・ 未実行、rollback、possible-permanent-delete、recycle-verification-contaminated を記録します。

設定

セル 項目 既定値 説明
C5 対象フォルダ (空) パスを直接貼り付けても良い
C6 最大階層 0 0 は無制限。N を指定するとルートから N 階層で打ち切る
C7 ファイルも一覧に含める はい 「いいえ」にするとフォルダ行だけを出力する
C8 隠し/システム属性も含める いいえ 「はい」にすると隠しファイル・隠しフォルダも対象にする

出力列(ツリー シート)

列 内容
名前 階層に応じてインデント。フォルダ行は太字+淡い背景色
種別 フォルダ / ファイル / リンク。権限エラー時は (一部アクセス不可) を付記
階層 ルートを 0 とした深さ
配下ファイル数 フォルダ行のみ。その配下すべてのファイル数の合計
サイズ(byte) フォルダ行は配下合計、ファイル行はそのファイルのサイズ
更新日時 最終更新日時
フルパス 絶対パス

仕様上の注意

改修後の信頼性契約

  • C6=0 はユーザー指定の階層上限なしを意味するが、暴走防止の内部安全弁512階層は別に適用する。安全弁到達時は打ち切り先の集計を含めず、サマリーへ通知する。

  • Esc は走査フェーズのみ受け付ける。出力・アウトライン設定中はEscを無効化し、処理済み範囲の部分結果を整合的に出力する。

  • FindNextFileW のerror 18以外の終了は列挙不完全として記録し、アクセス拒否とは別に表示する。

  • 名前・種別・フルパス・対象フォルダは文字列列として書き込むため、=, +, -, @ で始まる名前も数式として実行されない。

  • 1,000,000行は論理上限であり、追加失敗時に既存最終行を新規行として再利用しない。Excel bitnessと利用可能メモリにも依存する。

  • 処理中の再実行は拒否され、走査バッファ/スタックは変更されない。VBAの End またはVBEリセット後はmodule-level状態が初期化される。

  • 中断: Esc は走査フェーズで受け付ける。ファイル削除phaseは開始後に中断できないため、 確認画面の件数と所要時間を確認し、処理中にExcelを強制終了しない。

  • アクセス権: 読み取れないフォルダがあっても処理は継続し、該当行の 種別 に (一部アクセス不可) を表示する。件数は完了メッセージにも出る。

  • シンボリックリンク/ジャンクション: 無限再帰を避けるためリンク先はたどらない(種別 が リンク)。加えて、祖先と同じパスに到達した場合も循環として打ち切る。

  • 長いパス: 260 文字を超えるパスは \\?\ プレフィックスで扱うため、そのまま列挙できる。

  • 階層の上限: Excel のアウトラインは 8 階層までのため、9 階層以降は折りたたみ表示上 8 階層目として扱う。インデントは 15 階層まで反映される。

  • 打ち切り時の集計: 最大階層を指定した場合、打ち切った先のファイル数・サイズは合計に含まれない。

  • 行数の上限: 出力が 1,000,000 行に達すると打ち切り、完了メッセージで通知する。

  • クラウド同期ドライブ: Google ドライブ等の仮想ドライブでも動作する(下記「実装メモ」参照)。ただし OneDrive のオンデマンド同期対象では、属性取得で実体のダウンロードが発生する場合がある。

実測性能

一覧生成性能は、対話型WindowsセッションのExcel COMで測定しました。

出力行数 fixture作成 走査 変更一覧生成 Excel working set増分
10,000 4.51秒 0.84秒 0.32秒 106,872,832 bytes
100,000 38.48秒 4.65秒 3.18秒 314,855,424 bytes

両fixtureとも期待行数と実出力行数が一致し、変更一覧は部分生成なしで成功しました。連番100/1,000/10,000件、 100,001行fail-closed拒否も測定済みです。実ファイル削除は1/100/1,000件、空フォルダのゴミ箱移動は depth-group 1/3/8で実測し、全fixtureを元pathへ復元しました。

既知の制限

  • Shell ExtendedProperty latencyは少数の実Recycle Bin item数でのみ測定しており、10,000件・50,000件規模の実測値ではありません。
  • 削除件数1,001〜10,000件の所要時間は「見積不能」と表示されます。

Google ドライブ(クラウド同期ドライブ)上の大規模フォルダ(12,428 フォルダ / 50,821 ファイル / 最大 18 階層 / 出力 63,249 行)で実測した参考値です。所要時間は同期状態やネットワーク環境に依存します。

実装 所要時間
FileSystemObject + ブロックごとに OutlineLevel 代入 完走せず(実行時エラー 28 / ストール)
Win32 API 列挙 + ブロックごとに OutlineLevel 代入 303 秒
↑ + アウトラインをデータ書き込み前に設定 133 秒
↑ + 階層ごとの一括 Group(現行) 15 秒

開発

前提

  • Windows + Excel(デスクトップ版)
  • PowerShell 7 以上
  • 開発(ビルド・テスト)時のみ、Excel の トラスト センター > マクロの設定 > 「VBA プロジェクト オブジェクト モデルへのアクセスを信頼する」 を一時的に有効にする (レジストリ: HKCU:\Software\Microsoft\Office\<ver>\Excel\Security\AccessVBOM = 1)。 通常の利用者はこの設定を変更する必要はありません。

再ビルド

候補は -Profile Test(テスト専用wrapper procedureを含む)と -Profile Release(含まない)を 明示的に指定して生成する。src/*.bas はcanonicalなsourceであり、profileの切り替えはbuilderが 一時copyへ #Const TEST_BUILD を1行だけ挿入して行う。

pwsh -NoProfile -File scripts/build-xlsm.ps1 -CandidateOnly -Profile Test -OutputPath .build-work/<candidate>.xlsm

必須ケース1〜68、性能ゲートは対話型Windowsセッションで次のrunnerを使用します。candidate-only build、 必須ケース1〜68、100,001行fail-closed、連番100/1,000/10,000件を順番に検証し、配布物へは昇格しません。

pwsh -NoProfile -File scripts/run-release-validation.ps1

候補と同じ名前に .build-receipt.json を付けたcandidate build receiptも生成される。buildは固定値を記録するのではなく、 Open XML content type、xl/vbaProject.bin、VBAProjectの明示compile、シート順、設定!C7:C8、4ボタン、 embedded VBA本文、通常UI経路、閉じて再オープン後の維持を実検査する。

pwsh -NoProfile -File scripts/test-xlsm.ps1 `
  -WorkbookPath .build-work/<candidate>.xlsm `
  -CandidateBuildReceiptPath .build-work/<candidate>.xlsm.build-receipt.json `
  -GateReceiptPath .build-work/<candidate>.gate.json

VBA を変更する場合は src/*.bas を編集し、上記の -CandidateOnly 経路で候補を作成する。候補ゲートを通過した同一候補だけを、release手順(別文書)へ渡す。 .xlsm 内のコードを VBE で直接編集した場合、次回の候補ビルドで上書きされる点に注意。

生成スクリプトは、cp932 で表現できない文字が .bas に含まれている場合はビルドを中断する (VBE 取り込み時に文字化けするため)。

検証

repository内の一時作業領域(.test-work/<nonce>/)へ既知の階層を作り、RunScan マクロを実行して行順序・階層・集計値・ アウトライン/インデント・文字列安全性を突き合わせる。ブックは保存せずに閉じる。作業領域はテスト終了時に作成したnonce単位でcleanupする。 テスト専用の引数付き RunScanTest / ProbeReentry は、行上限、チャンク、確保失敗、 outline失敗、中断、再入拒否を注入するためのもので、通常のUIボタンからは呼び出さない。 candidate gate receiptはcandidate build receiptのhashへ結合され、必須ケース1〜68がすべて pass でなければ 昇格を拒否します。未実行ケースを pass として扱いません。ケース69の隔離SMB試験は任意supplemental receiptへ分離します。 ケース18は既知候補のコピーから xl/vbaProject.bin だけを除いた破損fixtureをExcelで開かず検証する。

pwsh -NoProfile -File scripts/test-xlsm.ps1 -WorkbookPath .build-work/<candidate>.xlsm

実装メモ

以下はいずれも実測にもとづく設計判断で、素直に書くと大きなツリーで破綻する箇所である。

  • 列挙に FileSystemObject を使わない。 FSO はファイル 1 件につき Attributes / Size / Name / Path / DateLastModified を それぞれ別の COM 呼び出しで取得するため、ファイルシステムドライバへの往復が 件数 × 5 回になる。Google ドライブのような仮想ドライブでは負荷が続くとストールし、 数万ファイル規模で事実上ハングする。 Win32 の FindFirstFileW / FindNextFileW なら 1 エントリ 1 回の呼び出しで 属性・サイズ・更新日時をまとめて取得でき、\\?\ プレフィックスで長いパスにも対応できる。

  • 再帰ではなく明示スタックによる反復処理。 VBA の再帰はスタック領域を使い切ると「実行時エラー 28: スタック領域が不足しています」で 停止し、しかもスタックが尽きているためエラーハンドラ自体が動かず、 ユーザーには原因不明のフリーズに見える。反復処理ならこの failure mode が消える。

  • アウトラインは「データを書き込む前」に設定する。 同じ操作でも、データが入ったシートに対して行うと 1 回あたり約 9 倍遅くなる (実測 10.8 ms → 1.2 ms)。

  • アウトラインは OutlineLevel 代入ではなく階層ごとの Group。 OutlineLevel も Group も複数範囲をまとめた Range を受け付けない (「複数の選択範囲に対してこの機能を実行することはできません」)ため、 単一範囲で呼び出すしかなく、呼び出し回数がそのままコストになる。 「連続ブロックごとに OutlineLevel を代入」だと 63,249 行で 19,276 回必要だが、 「階層 L 以上の行のかたまりを Group する」を L=1..7 で繰り返すと 2,549 回で済む(87% 削減)。 行 d は d 回グループ化され、結果として OutlineLevel = min(d + 1, 8) になる。 なお OutlineLevel を直接代入する場合、親階層が未設定だと子階層も設定できない点にも注意。

  • BuildTree(UI)と RunScan(スキャン本体)を分離してある。 RunScan はダイアログを出さず結果サマリーを文字列で返すため、自動テストから直接呼び出せる。

  • 出力バッファは「列 × 行」の 2 次元配列で保持している。 VBA の ReDim Preserve は最終次元しか拡張できないため、行を最終次元に置いたうえで 書き込み直前に転置する。確保に失敗した場合は UBound で検知して打ち切る。

  • インデントは複数範囲をまとめて設定できる。 アウトラインと違い IndentLevel は 多重範囲の Range へ代入できるので、階層ごとにアドレス文字列を束ねている (Range のアドレス文字列は 255 文字までなので 200 文字で分割する)。

About

No description or website provided.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages