docs: map existing codebase

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 09:28:40 +02:00
parent 10bfe6debc
commit 63cf69f114
7 changed files with 1490 additions and 0 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,249 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-02
+
+## Directory Layout
+
+```
+Sharepoint-Toolbox/
+├── .planning/                          # GSD planning documentation
+├── .git/                               # Git repository
+├── .gitea/                             # Gitea configuration
+├── .claude/                            # Claude IDE configuration
+├── examples/                           # CSV example files for bulk operations
+│   ├── bulk_add_members.csv            # Template: add users to groups
+│   ├── bulk_create_sites.csv           # Template: create multiple sites
+│   ├── bulk_transfer.csv               # Template: transfer site ownership
+│   └── folder_structure.csv            # Template: create folder hierarchies
+├── lang/                               # Language/localization files
+│   └── fr.json                         # French language translations
+├── Sharepoint_ToolBox.ps1              # Main application (6408 lines)
+├── Sharepoint_Settings.json            # User settings (data folder, language preference)
+├── Sharepoint_Export_profiles.json     # Saved connection profiles (generated at runtime)
+├── Sharepoint_Templates.json           # Saved site templates (generated at runtime)
+├── README.md                           # Documentation and feature overview
+├── TODO.md                             # Future feature roadmap
+└── SPToolbox-logo.png                  # Application logo
+```
+
+## Directory Purposes
+
+**`examples/`:**
+- Purpose: Reference CSV templates for bulk operations
+- Contains: CSV example files demonstrating column structure for bulk tasks
+- Key files:
+  - `bulk_add_members.csv`: User email and group name mappings
+  - `bulk_create_sites.csv`: Site title, URL, type, language
+  - `bulk_transfer.csv`: Source site, target owner email
+  - `folder_structure.csv`: Folder paths to create under libraries
+- Non-versioned: May contain user data after operations
+- Access: Referenced by bulk operation dialogs; templates shown in UI
+
+**`lang/`:**
+- Purpose: Store language packs for UI localization
+- Contains: JSON files with key-value pairs for UI text
+- Key files:
+  - `fr.json`: Complete French translations for all UI elements, buttons, messages
+- Naming: `<language-code>.json` (e.g., `en.json`, `fr.json`)
+- Loading: `Load-Language` function (line 2933) reads and caches translation dict
+- Integration: `T("key")` function (line 2908) looks up translations at runtime
+
+**`.planning/`:**
+- Purpose: GSD (GitHub Sync & Deploy) planning and analysis documents
+- Contains: Generated documentation for architecture, structure, conventions, concerns
+- Generated: By GSD mapping tools; not manually edited
+- Committed: Yes, tracked in version control
+
+## Key File Locations
+
+**Entry Points:**
+
+- `Sharepoint_ToolBox.ps1` (lines 1-6408): Single monolithic PowerShell script
+  - Execution: `.ps1` file run directly or sourced from PowerShell ISE/terminal
+  - Initialization: Lines 6386-6408 load settings, language, profiles, then show main form
+  - Exit: Triggered by form close or exception; automatic cleanup of runspaces
+
+- Main GUI Form instantiation: `Sharepoint_ToolBox.ps1` line 2992
+  - Creates WinForms.Form object
+  - Registers all event handlers
+  - Shows dialog via `[void]$form.ShowDialog()` at line 6405
+
+**Configuration:**
+
+- `Sharepoint_Settings.json`: User preferences
+  - Structure: `{ "dataFolder": "...", "lang": "en" }`
+  - Loaded by: `Load-Settings` (line 136)
+  - Saved by: `Save-Settings` (line 147)
+  - Auto-created: If missing, defaults to English + script root directory
+
+- `Sharepoint_Export_profiles.json`: Connection profiles (auto-created)
+  - Structure: `{ "profiles": [ { "name": "Prod", "clientId": "...", "tenantUrl": "..." }, ... ] }`
+  - Loaded by: `Load-Profiles` (line 57)
+  - Saved by: `Save-Profiles` (line 68)
+  - Location: Determined by `Get-ProfilesFilePath` (line 50) - same as settings
+
+- `Sharepoint_Templates.json`: Captured site templates (auto-created)
+  - Structure: `{ "templates": [ { "name": "...", "libraries": [...], "groups": [...], ... }, ... ] }`
+  - Loaded by: `Load-Templates` (line 484)
+  - Saved by: `Save-Templates` (line 495)
+  - Location: Same folder as profiles/settings
+
+**Core Logic:**
+
+- Permissions Report: `Sharepoint_ToolBox.ps1` lines 1784-2001
+  - `Generate-PnPSitePermissionRpt` (line 1852): Main permission scanning function
+  - `Get-PnPWebPermission` (line 1944): Recursive site/subsite scanning
+  - `Get-PnPListPermission` (line 1912): Library and list enumeration
+  - `Get-PnPFolderPermission` (line 1882): Folder-level permission scanning
+  - `Get-PnPPermissions` (line 1786): Individual role assignment extraction
+
+- Storage Metrics: `Sharepoint_ToolBox.ps1` lines 2002-2110
+  - `Get-SiteStorageMetrics` (line 2004): Main storage scan function
+  - Nested `Collect-FolderStorage` (line 2010): Recursive folder traversal
+  - Nested `Collect-WebStorage` (line 2034): Per-web storage collection
+
+- File Search: `Sharepoint_ToolBox.ps1` lines 2112-2233
+  - Search API integration via PnP.PowerShell
+  - KQL (Keyword Query Language) filter construction
+  - Client-side regex filtering after API retrieval
+
+- Template Management: `Sharepoint_ToolBox.ps1` lines 475-1360
+  - `Show-TemplateManager` (line 542): Template dialog
+  - Capture state machine in dialog event handlers
+  - Template persistence via JSON serialization
+
+- Duplicate Detection: `Sharepoint_ToolBox.ps1` lines 2235-2408
+  - File mode: Search API with grouping by filename
+  - Folder mode: Direct library enumeration + comparison
+  - HTML export with grouped UI
+
+**Testing:**
+
+- No automated test framework present
+- Manual testing via GUI interaction
+- Examples folder (`examples/`) provides test data templates
+
+**Localization:**
+
+- `lang/fr.json`: French translations
+  - Format: JSON object with `"_name"` and `"_code"` metadata + translation keys
+  - Loading: `Load-Language` (line 2933) parses JSON into `$script:LangDict`
+  - Usage: `T("key")` replaces hardcoded English strings with translations
+  - UI Update: `Update-UILanguage` (line 2951) updates all registered controls
+
+## Naming Conventions
+
+**Files:**
+
+- Main application: `Sharepoint_ToolBox.ps1` (PascalCase with underscore separator)
+- Settings/data: `Sharepoint_<Type>.json` (e.g., `Sharepoint_Settings.json`)
+- Generated exports: `<Report>_<site>_<timestamp>.<format>` or `<Report>_<mode>_<timestamp>.<format>`
+  - Permissions: `Permissions_<site>_<yyyyMMdd_HHmmss>.csv/html`
+  - Storage: `Storage_<site>_<yyyyMMdd_HHmmss>.csv/html`
+  - Search: `FileSearch_<yyyyMMdd_HHmmss>.csv/html`
+  - Duplicates: `Duplicates_<mode>_<yyyyMMdd_HHmmss>.csv/html`
+- Language files: `<language-code>.json` (lowercase, e.g., `fr.json`)
+- Example files: `<operation>_<type>.csv` (lowercase with underscore, e.g., `bulk_add_members.csv`)
+
+**PowerShell Functions:**
+
+- Public functions: `Verb-Noun` naming (e.g., `Generate-PnPSitePermissionRpt`, `Get-SiteStorageMetrics`)
+- Private/internal functions: Prefixed with `_` or grouped in regions (e.g., `_Pkl-Sort`, `_Pkl-Repopulate`)
+- Event handlers: Declared inline in `.Add_Click` or `.Add_TextChanged` blocks; not named separately
+- Nested functions (inside others): CamelCase with parent context (e.g., `Collect-FolderStorage` inside `Get-SiteStorageMetrics`)
+
+**Variables:**
+
+- Script-scope state: `$script:<name>` (e.g., `$script:AllPermissions`, `$script:DataFolder`)
+- Local function scope: camelCase (e.g., `$result`, `$dlg`, `$lists`)
+- Control references: descriptive with type suffix (e.g., `$txtClientId`, `$btnPermRun`, `$cboProfile`)
+- Control variables stored in script scope: Prefixed `$script:` for access across event handlers
+- Temporary arrays: `$<plural>` (e.g., `$sites`, `$folders`, `$results`)
+
+**Types:**
+
+- Region markers: `#region ===== <Name> =====` (e.g., `#region ===== GUI =====`)
+- Comments: Double hash for section comments (e.g., `# ── Label helper ──`)
+
+**Exports:**
+
+- HTML: Class names like `permission-table`, `storage-tree`, `duplicate-group`
+- CSV: Column headers match object property names (e.g., `Title`, `URL`, `Permissions`)
+
+## Where to Add New Code
+
+**New Feature:**
+
+1. Create a new region section in `Sharepoint_ToolBox.ps1`:
+   ```powershell
+   #region ===== [Feature Name] =====
+   function [Verb]-[Feature](...) { ... }
+   #endregion
+   ```
+
+2. Primary code locations:
+   - Core logic: After line 2408 (after duplicates region, before Transfer region)
+   - PnP interaction: Own `#region` mirroring storage/permissions pattern
+   - HTML export helper: Create function like `Export-[Feature]ToHTML` in dedicated region
+
+3. Add UI tab or button:
+   - Create new TabPage in `$tabs` (around line 3113+)
+   - Register event handler for execution button in Event Handlers region (line 4068+)
+   - Add label in French translation file (`lang/fr.json`)
+
+4. Add menu item if needed:
+   - Modify MenuStrip construction around line 3001-3027
+   - Register handler in Event Handlers region
+
+5. Persist settings:
+   - Add properties to `Sharepoint_Settings.json` structure
+   - Update `Load-Settings` (line 136) to include new fields
+   - Update `Save-Settings` (line 147) to serialize new fields
+
+**New Component/Module:**
+
+- Keep as internal functions (no separate files)
+- If complexity exceeds 500 lines, consider refactoring into regions
+- Pattern: All code stays in single `Sharepoint_ToolBox.ps1` file
+- Dependencies: Use script-scope variables for shared state
+
+**Utilities:**
+
+- Shared helpers: `Shared Helpers` region (line 4-46)
+  - Add new helper function here if used by multiple features
+  - Examples: `Write-Log`, `Format-Bytes`, `EscHtml`, `Validate-Inputs`
+
+- UI control factories: Lines 3119-3146
+  - Add new `New-<Control>` helper for frequently used UI patterns
+  - Examples: `New-Group`, `New-Check`, `New-Radio`, `New-ActionBtn`
+
+- Internationalization: `Internationalization` region (line 2732-2989)
+  - Add new translation keys to `lang/fr.json`
+  - Update `T()` function if new resolution logic needed
+
+## Special Directories
+
+**`examples/`:**
+- Purpose: CSV templates for user reference
+- Generated: No; committed as examples
+- Committed: Yes, tracked in version control
+- Accessed by: Bulk operation dialogs (not directly imported by code; users download manually)
+- Content: Non-executable; user-facing documentation
+
+**`.planning/`:**
+- Purpose: GSD-generated codebase analysis and planning documents
+- Generated: Yes; created by GSD mapping tools during `/gsd:map-codebase`
+- Committed: Yes; documents are version-controlled
+- Accessed by: `/gsd:plan-phase` and `/gsd:execute-phase` commands for context
+- Content: Markdown documents describing architecture, structure, conventions, concerns, stack, integrations
+
+**Generated Files (Runtime):**
+
+Files created at runtime, not part of initial repository:
+- `Sharepoint_Export_profiles.json`: User-created connection profiles
+- `Sharepoint_Templates.json`: User-captured site templates
+- Export reports: `*_<timestamp>.(csv|html)` files in output folder (default: script root or user-selected)
+
+---
+
+*Structure analysis: 2026-04-02*