Skip to content

Commit 324385a

Browse files
authored
1 parent c2f4ef3 commit 324385a

File tree

3 files changed

+409
-266
lines changed

3 files changed

+409
-266
lines changed

docs/architecture/index.md

Lines changed: 149 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,36 +4,160 @@ This section explains the overall architecture of the Workspace Wiki extension,
44

55
## Main Components
66

7-
- **Scanner/Indexer**: Discovers documentation files in the workspace, caches metadata, and watches for changes.
8-
- **TreeDataProvider**: Renders the documentation tree in the sidebar, applying ordering and title normalization.
9-
- **Preview/Open Controller**: Handles file opening (preview/editor) and user interactions.
10-
- **Settings Manager**: Reads and applies extension settings.
11-
- **Sync Module**: Keeps the tree in sync with the active editor.
12-
- **Utilities**: Helpers for title normalization and file type detection.
7+
- **[Scanner](../../src/scanner/workspaceScanner.ts)**: Discovers documentation files using `workspace.findFiles`, respects `.gitignore` and exclude patterns, filters hidden files, and returns URIs.
8+
- **[Tree Provider](../../src/tree/treeProvider.ts)**: Implements VS Code's `TreeDataProvider` interface, builds hierarchical tree structure, applies ordering rules, manages node mapping for sync.
9+
- **[Tree Builder](../../src/tree/buildTree.ts)**: Constructs hierarchical tree from flat file list, calculates common base path, sorts nodes, handles folder/file relationships.
10+
- **[Preview Controller](../../src/controllers/previewController.ts)**: Handles file opening with double-click detection (500ms threshold), manages preview vs editor modes, respects `openWith` configuration.
11+
- **[Configuration Utilities](../../src/utils/configUtils.ts)**: Provides typed access to extension settings with default values.
12+
- **[Text Utilities](../../src/utils/textUtils.ts)**: Normalizes file names to human-readable titles, preserves acronym casing, handles special cases (README).
13+
- **[File Utilities](../../src/utils/fileUtils.ts)**: Path manipulation, hidden file detection, glob pattern matching.
14+
- **[Sync Module](../../src/extension.ts)**: Integrated into main extension activation, reveals active file in tree with configurable delay, respects visibility state.
15+
16+
## Source Code Structure
17+
18+
```text
19+
src/
20+
├── extension.ts # Extension activation, command registration, sync logic
21+
├── controllers/
22+
│ ├── index.ts
23+
│ └── previewController.ts # File opening, double-click detection
24+
├── scanner/
25+
│ ├── index.ts
26+
│ └── workspaceScanner.ts # File discovery, filtering
27+
├── tree/
28+
│ ├── index.ts
29+
│ ├── buildTree.ts # Tree construction, sorting
30+
│ └── treeProvider.ts # VS Code TreeDataProvider implementation
31+
├── types/
32+
│ ├── index.ts
33+
│ ├── treeNode.ts # TreeNode interface
34+
│ └── workspaceLike.ts # Workspace abstraction for testing
35+
└── utils/
36+
├── index.ts
37+
├── configUtils.ts # Configuration access
38+
├── fileUtils.ts # Path utilities
39+
└── textUtils.ts # Title normalization
40+
```
1341

1442
## Subpages
1543

16-
- [Scanner/Indexer](./scanner.md)
17-
- [TreeDataProvider](./tree-data-provider.md)
18-
- [Preview/Open Controller](./preview-controller.md)
19-
- [Settings Manager](./settings.md)
20-
- [Sync Module](./sync.md)
21-
- [Utilities](./utilities.md)
44+
- [Scanner](./scanner.md) - File discovery and filtering logic
45+
- [Tree Data Provider](./tree-data-provider.md) - Tree view implementation
46+
- [Preview Controller](./preview-controller.md) - File opening behavior
47+
- [Settings](./settings.md) - Configuration options
48+
- [Sync Module](./sync.md) - Active file revelation
49+
- [Utilities](./utilities.md) - Helper functions
2250

23-
## Architecture Overview Diagram
51+
## Architecture Diagram
2452

2553
```mermaid
26-
flowchart TD
27-
A[Scanner/Indexer] -->|Discovers files| B[TreeDataProvider]
28-
B -->|Displays tree| C[VS Code Sidebar]
29-
B -->|Opens file| D[Preview/Open Controller]
30-
D -->|Uses| E[VS Code Editor]
31-
A -->|Reads| F[Settings Manager]
32-
D -->|Reads| F
33-
F -->|Syncs| G[Sync Module]
34-
B -->|Uses| H[Utilities]
35-
A -->|Uses| H
36-
D -->|Uses| H
54+
flowchart TB
55+
subgraph Extension["Extension (src/extension.ts)"]
56+
A[activate]
57+
B[Command Registration]
58+
C[Sync Logic]
59+
end
60+
61+
subgraph Scanner["Scanner (src/scanner/)"]
62+
D[scanWorkspaceDocs]
63+
E[Filter by Extensions]
64+
F[Apply .gitignore]
65+
G[Filter Hidden Files]
66+
end
67+
68+
subgraph Tree["Tree (src/tree/)"]
69+
H[WorkspaceWikiTreeProvider]
70+
I[buildTree]
71+
J[sortNodes]
72+
K[Node Mapping]
73+
end
74+
75+
subgraph Controllers["Controllers (src/controllers/)"]
76+
L[handleFileClick]
77+
M[openInPreview]
78+
N[openInEditor]
79+
end
80+
81+
subgraph Utils["Utilities (src/utils/)"]
82+
O[normalizeTitle]
83+
P[configUtils]
84+
Q[fileUtils]
85+
end
86+
87+
subgraph VSCode["VS Code API"]
88+
R[TreeView]
89+
S[Commands]
90+
T[Workspace]
91+
U[Window]
92+
end
93+
94+
A --> B
95+
A --> C
96+
A --> H
97+
B --> S
98+
C --> R
99+
100+
H --> D
101+
D --> E
102+
E --> F
103+
F --> G
104+
G --> I
105+
I --> J
106+
I --> O
107+
108+
H --> K
109+
K --> C
110+
111+
R --> H
112+
H --> L
113+
L --> M
114+
L --> N
115+
M --> S
116+
N --> S
117+
118+
D --> T
119+
H --> P
120+
I --> O
121+
D --> Q
37122
```
38123

39-
This diagram shows the main modules and their interactions. The Scanner/Indexer discovers files, which are passed to the TreeDataProvider for display. The Preview/Open Controller manages file opening, and all modules use the Settings Manager and Utilities as needed. The Sync Module keeps the tree in sync with the active editor.
124+
## Data Flow
125+
126+
```mermaid
127+
sequenceDiagram
128+
participant User
129+
participant VSCode as VS Code
130+
participant Extension
131+
participant Scanner
132+
participant TreeProvider
133+
participant TreeView
134+
participant Controller
135+
136+
User->>VSCode: Opens workspace
137+
VSCode->>Extension: activate()
138+
Extension->>TreeProvider: new WorkspaceWikiTreeProvider()
139+
Extension->>VSCode: createTreeView('workspaceWiki')
140+
VSCode->>TreeView: Create tree view
141+
142+
TreeView->>TreeProvider: getChildren()
143+
TreeProvider->>Scanner: scanWorkspaceDocs()
144+
Scanner->>VSCode: workspace.findFiles()
145+
VSCode-->>Scanner: File URIs
146+
Scanner-->>TreeProvider: Filtered URIs
147+
TreeProvider->>TreeProvider: buildTree(uris)
148+
TreeProvider-->>TreeView: TreeItems
149+
TreeView-->>User: Display tree
150+
151+
User->>TreeView: Click file
152+
TreeView->>Controller: handleFileClick(uri)
153+
Controller->>Controller: Detect single/double click
154+
Controller->>VSCode: executeCommand(openWith)
155+
VSCode-->>User: Show file in editor
156+
157+
User->>VSCode: Change active editor
158+
VSCode->>Extension: onDidChangeActiveTextEditor
159+
Extension->>TreeProvider: findNodeByPath()
160+
TreeProvider-->>Extension: TreeNode
161+
Extension->>TreeView: reveal(node)
162+
TreeView-->>User: Highlight file in tree
163+
```

0 commit comments

Comments
 (0)