# file-view-tree

**Repository Path**: ftJ2one/file-view-tree

## Basic Information

- **Project Name**: file-view-tree
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NPC FileTree Viewer 🌲

<!-- Plugin description -->
NPC FileTree Viewer is a directory visualization tool designed for developers.
It supports regex matching, automatic file comment extraction, and generates
physically aligned ASCII trees for clear project documentation.

**一款专为开发者设计的目录结构可视化工具：**

- **正则匹配**：支持灵活的正则表达式筛选目录与文件。
- **注释提取**：自动提取文件头注释并展示在结构树中。
- **物理对齐**：生成规整的 ASCII 树，方便粘贴到文档中。

<!-- Plugin description end -->

## 效果图

| 配置                                                                          | 视图                                                                       |
|-----------------------------------------------------------------------------|--------------------------------------------------------------------------|
| ![配置](https://gitee.com/ftJ2one/file-view-tree/raw/main/assets/config.jpg) | ![视图](https://gitee.com/ftJ2one/file-view-tree/raw/main/assets/view.jpg) |

## ✨ 核心特性

* **🧪 漏斗式过滤逻辑**：严格遵循 `文件夹准入 -> 文件夹黑名单 -> 文件白/黑名单` 的层级过滤链。
* **📏 智能注释对齐**：自动识别类说明、Swagger 标签及 Javadoc，并实现物理层面的视觉对齐。
* **🔗 路径自动保留**：当深层文件命中白名单时，自动保留其所有父级路径，确保树型逻辑完整。
* **🎯 层级精准控制**：支持 `level:regex` 语法（如 `1:^src`），精确控制特定深度的扫描行为。

---

## 🚀 规则使用手册 (Regex Logic Flow)

为了实现最精确的过滤，插件采用了**“三级漏斗”**模型。建议按以下顺序配置规则：

### 1. 核心过滤流程

| 阶段         | 配置项                     | 逻辑描述                                            |
|:-----------|:------------------------|:------------------------------------------------|
| **Step 1** | **指定文件夹 (Include Dir)** | **准入制**：只有名字匹配的目录才允许进入扫描范围。                     |
| **Step 2** | **过滤文件夹 (Exclude Dir)** | **黑名单**：在准入目录中，彻底剔除不需要的子目录（如 `target`, `test`）。 |
| **Step 3** | **指定文件 (Include File)** | **筛选器**：在最终保留的目录中，仅展示符合规则的文件（如 `.*Controller`）。 |

### 2. 匹配技巧与正则示例

* **全字匹配 (推荐)**：使用 `^api$` 确保只匹配名为 `api` 的文件夹，防止误伤 `apijson` 或 `openapi`。
* **模糊匹配**：直接输入 `service` 将匹配路径中任何包含该字符串的目录。
* **层级限定**：`2:^impl$` 表示仅在目录树的**第 2 层**匹配以 `impl` 结尾的文件夹。
* **文件后缀**：匹配 Java 文件请使用 `.*\.java$`（注意正则中点号需要转义）。

---

## 🔍 注释扫描原理 (Metadata Extraction)

插件在生成树时，会智能读取文件前 **2000 字节**的内容，并按以下优先级自动提取业务说明：

| 优先级   | 目标类型                    | 匹配逻辑示例                                 |
|:------|:------------------------|:---------------------------------------|
| **1** | **Swagger / SpringDoc** | 提取 `@Tag(name = "用户接口")` 中的 `name` 属性值 |
| **2** | **通用描述**                | 识别 `@description` 后紧跟的文字描述             |
| **3** | **标准 Javadoc**          | 抓取 `/** ... */` 块中第一行有效的非注解文字          |
| **4** | **行首中文注释**              | 匹配以 `//` 开头且包含**中文字符**的行               |

---

## 🛠️ 开发者指南 (Development & Test)

### 本地开发与测试

1. **运行沙盒**: 在 IntelliJ 右侧 Gradle 面板执行 `Tasks -> intellij -> runIde`。这将启动一个预装了插件的隔离 IDEA 环境。
2. **逻辑调试**: 核心算法位于 `FileTreeGenerator.kt`。建议在 `src/test` 编写 JUnit 用例，模拟不同的 `VirtualFile`
   结构验证正则命中率。
3. **UI 调试**: 修改面板布局后，可尝试使用 `Reload Fixed Plugins` (需开启 IDEA 内部模式) 实现快速热更新。

### 打包与发版

项目基于 `gradle-intellij-plugin` 构建：

1. **构建离线包**: 执行 `./gradlew buildPlugin`，生成的 `.zip` 包位于 `build/distributions/`。
2. **兼容性验证**: 执行 `./gradlew runPluginVerifier` 检查不同 IDE 版本的 API 兼容性。
3. **上架商城**: 配置 [Marketplace Token](https://plugins.jetbrains.com/author/me/tokens) 后，执行
   `./gradlew publishPlugin`。

---

## 📦 安装方式

1. 在 IDEA 中进入 `Settings -> Plugins`。
2. 搜索 `NPC FileTree Viewer` (若已上架)。
3. 或下载 `zip` 离线包通过 `Install Plugin from Disk...` 手动安装。