chore: complete v1.0 milestone
Archive 5 phases (36 plans) to milestones/v1.0-phases/. Archive roadmap, requirements, and audit to milestones/. Evolve PROJECT.md with shipped state and validated requirements. Collapse ROADMAP.md to one-line milestone summary. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dev
152
.planning/milestones/v1.0-phases/02-permissions/02-02-SUMMARY.md
Normal file
152
.planning/milestones/v1.0-phases/02-permissions/02-02-SUMMARY.md
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
phase: 02-permissions
|
||||
plan: 02
|
||||
subsystem: permissions
|
||||
tags: [csom, sharepoint, permissions, scan-engine, pnp, c-sharp]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 02-01
|
||||
provides: PermissionEntryHelper (IsExternalUser, FilterPermissionLevels, IsSharingLinksGroup)
|
||||
provides:
|
||||
- PermissionEntry record — flat data model for one permission assignment
|
||||
- ScanOptions record — immutable scan configuration with IncludeInherited/ScanFolders/FolderDepth/IncludeSubsites
|
||||
- IPermissionsService interface — contract enabling ViewModel mocking in tests
|
||||
- PermissionsService implementation — full CSOM scan engine, port of PS Generate-PnPSitePermissionRpt
|
||||
affects:
|
||||
- 02-04 (PermissionsViewModel uses IPermissionsService)
|
||||
- 02-05 (Export services work on IReadOnlyList<PermissionEntry>)
|
||||
- 02-06 (SitePickerDialog feeds site URLs into PermissionsService)
|
||||
- 02-07 (Full integration wires PermissionsService into DI)
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "CSOM batched Include() load pattern — one round-trip per SecurableObject via ctx.Load + ExecuteQueryRetryHelper"
|
||||
- "Async folder enumeration via SharePointPaginationHelper.GetAllItemsAsync (never raw CSOM list enumeration)"
|
||||
- "HashSet<string> ExcludedLists for O(1) system list filtering"
|
||||
- "PrincipalType detection via PermissionEntryHelper.IsExternalUser before CSOM PrincipalType enum"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- SharepointToolbox/Core/Models/PermissionEntry.cs
|
||||
- SharepointToolbox/Core/Models/ScanOptions.cs
|
||||
- SharepointToolbox/Services/IPermissionsService.cs
|
||||
- SharepointToolbox/Services/PermissionsService.cs
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "Folder enumeration uses ListItem (SecurableObject) not Folder — Folder is not a SecurableObject in CSOM; ListItem.Folder provides metadata while ListItem itself holds role assignments"
|
||||
- "Principal.Email excluded from CSOM Include — Principal base type has no Email property; only User subtype does; email not needed for PermissionEntry fields"
|
||||
- "FolderDepth=999 is the sentinel for unlimited depth — avoids nullable int and matches PS reference behavior"
|
||||
- "Subsite enumeration clones ClientContext via ctx.Clone(subweb.Url) — each subsite needs its own context for CSOM scoped operations"
|
||||
|
||||
patterns-established:
|
||||
- "CSOM batched load: always batch ctx.Load with all required sub-properties in one call before ExecuteQueryRetryAsync"
|
||||
- "ExcludedLists HashSet: new service that filters SharePoint objects uses StringComparer.OrdinalIgnoreCase HashSet for O(1) exclusion"
|
||||
- "ct.ThrowIfCancellationRequested() at the start of every private async method"
|
||||
|
||||
requirements-completed:
|
||||
- PERM-01
|
||||
- PERM-03
|
||||
- PERM-04
|
||||
- PERM-07
|
||||
|
||||
# Metrics
|
||||
duration: 7min
|
||||
completed: 2026-04-02
|
||||
---
|
||||
|
||||
# Phase 2 Plan 2: PermissionsService Scan Engine Summary
|
||||
|
||||
**CSOM scan engine implementing all 5 SharePoint permission scan paths (site collection admins, web, lists, folders, subsites) as a faithful C# port of the PowerShell Generate-PnPSitePermissionRpt function**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 7 min
|
||||
- **Started:** 2026-04-02T11:48:39Z
|
||||
- **Completed:** 2026-04-02T11:54:58Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 4
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Defined PermissionEntry (9-field record), ScanOptions (4-field config record), and IPermissionsService interface — foundational contracts for all subsequent Phase 2 plans
|
||||
- Implemented PermissionsService with full scan logic: site collection admins, web, lists, folders (via SharePointPaginationHelper), and subsites
|
||||
- All CSOM round-trips use ExecuteQueryRetryHelper.ExecuteQueryRetryAsync; folder enumeration uses SharePointPaginationHelper.GetAllItemsAsync (never raw iteration)
|
||||
- Limited Access filtering, sharing links group exclusion, external user detection, and 34-item ExcludedLists set all implemented
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Define data models and IPermissionsService interface** - `4a6594d` (feat)
|
||||
2. **Task 2: Implement PermissionsService scan engine** - `9f2e2f9` (fix — linter auto-fixed CSOM type errors pre-commit)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `SharepointToolbox/Core/Models/PermissionEntry.cs` — Flat record for one permission assignment (9 string/bool positional fields)
|
||||
- `SharepointToolbox/Core/Models/ScanOptions.cs` — Immutable scan config: IncludeInherited, ScanFolders, FolderDepth, IncludeSubsites
|
||||
- `SharepointToolbox/Services/IPermissionsService.cs` — Interface with ScanSiteAsync enabling ViewModel mocking
|
||||
- `SharepointToolbox/Services/PermissionsService.cs` — Full CSOM engine: 340 lines, 5 private helpers, 34-item ExcludedLists
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- `Folder` is not a `SecurableObject` in CSOM — folder permissions are extracted via `ListItem` (which IS a SecurableObject); `item.Folder` provides name/URL metadata only
|
||||
- `Principal.Email` excluded from batched Include — `Principal` base type lacks Email; only `User` subtype has it; email was not needed for PermissionEntry fields
|
||||
- `FolderDepth=999` used as sentinel for unlimited depth scanning
|
||||
- Subsite enumeration clones ClientContext via `ctx.Clone(subweb.Url)` for proper CSOM scoping
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Principal.Email not available on RoleAssignment.Member**
|
||||
- **Found during:** Task 2 (PermissionsService implementation)
|
||||
- **Issue:** The plan's CSOM Include expression included `ra => ra.Member.Email` — Principal base type has no Email property (only User subtype does)
|
||||
- **Fix:** Removed Email from the batched Include; email is not needed for any PermissionEntry field
|
||||
- **Files modified:** SharepointToolbox/Services/PermissionsService.cs
|
||||
- **Verification:** dotnet build passes with 0 errors
|
||||
- **Committed in:** 9f2e2f9
|
||||
|
||||
**2. [Rule 1 - Bug] Folder is not a SecurableObject in CSOM**
|
||||
- **Found during:** Task 2 (GetFolderPermissionsAsync)
|
||||
- **Issue:** `ExtractPermissionsAsync(ctx, folder, ...)` failed — Folder does not inherit from SecurableObject in Microsoft.SharePoint.Client
|
||||
- **Fix:** Changed to pass `item` (ListItem, which IS a SecurableObject) to ExtractPermissionsAsync; kept `item.Folder` load for ServerRelativeUrl/Name metadata only
|
||||
- **Files modified:** SharepointToolbox/Services/PermissionsService.cs
|
||||
- **Verification:** dotnet build passes with 0 errors
|
||||
- **Committed in:** 9f2e2f9
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed (2 Rule 1 bugs — CSOM API type constraints)
|
||||
**Impact on plan:** Both fixes were necessary for correct CSOM usage. Folder permission extraction is semantically equivalent — ListItem holds the same role assignments as Folder. No scope creep.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- Pre-existing test failures (6): CsvExportService and HtmlExportService tests throw NotImplementedException — these are intentional stubs from Plan 01 to be implemented in Plan 03. No regression introduced by this plan.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- PermissionEntry, ScanOptions, IPermissionsService, and PermissionsService are available for Plans 02-04 (ViewModel), 02-05 (Export), 02-06 (SitePicker), and 02-07 (full integration)
|
||||
- All Phase 1 tests remain at 53 passing (plus 4 skipping, 6 pre-existing Plan 03 stubs failing)
|
||||
- IPermissionsService is mockable — PermissionsViewModelTests can be unblocked in Plan 04
|
||||
|
||||
---
|
||||
*Phase: 02-permissions*
|
||||
*Completed: 2026-04-02*
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: SharepointToolbox/Core/Models/PermissionEntry.cs
|
||||
- FOUND: SharepointToolbox/Core/Models/ScanOptions.cs
|
||||
- FOUND: SharepointToolbox/Services/IPermissionsService.cs
|
||||
- FOUND: SharepointToolbox/Services/PermissionsService.cs
|
||||
- FOUND: .planning/phases/02-permissions/02-02-SUMMARY.md
|
||||
- FOUND: commit 4a6594d (feat(02-02): define models and interface)
|
||||
- FOUND: commit 9f2e2f9 (fix(02-01): PermissionsService + export stubs)
|
||||
Reference in New Issue
Block a user