116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
# Quickstart: Baseline Compare Engine Strategy Extraction
|
|
|
|
## Goal
|
|
|
|
Extract the current Intune-shaped compare processing behind one explicit compare strategy while preserving the existing baseline compare run lifecycle, finding lifecycle, trust semantics, and operator-facing compare story.
|
|
|
|
## Prerequisites
|
|
|
|
1. Work on branch `203-baseline-compare-strategy`.
|
|
2. Ensure the platform containers are available:
|
|
|
|
```bash
|
|
cd apps/platform && ./vendor/bin/sail up -d
|
|
```
|
|
|
|
3. Keep Spec 202's canonical scope contract available because strategy selection depends on Baseline Scope V2.
|
|
|
|
## Recommended Implementation Order
|
|
|
|
### 1. Lock the current compare behavior with focused regression tests
|
|
|
|
Run the existing compare-focused suite before extracting anything:
|
|
|
|
```bash
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineComparePreconditionsTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareFindingsTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareGapClassificationTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareRbacRoleDefinitionsTest.php
|
|
```
|
|
|
|
Add any missing tests for unsupported scope, mixed-strategy scope, and current Intune compare classification parity before moving major compare logic.
|
|
|
|
### 2. Introduce the compare strategy contract and selection result
|
|
|
|
Add the narrow compare-support namespace under `app/Support/Baselines/Compare/` with:
|
|
|
|
- compare strategy contract
|
|
- strategy capability registry
|
|
- strategy selection result
|
|
- compare subject result contract
|
|
|
|
Keep these objects internal and derived. Do not add a new table or new `OperationRun` type.
|
|
|
|
### 3. Wire strategy validation into compare start surfaces
|
|
|
|
Update `BaselineCompareService` so both:
|
|
|
|
- tenant compare start
|
|
- workspace compare-matrix fan-out compare
|
|
|
|
resolve one compatible strategy family from canonical scope before any run is enqueued.
|
|
|
|
Unsupported or mixed-scope requests should fail clearly before subject work begins.
|
|
|
|
### 4. Extract the current Intune compare implementation behind `IntuneCompareStrategy`
|
|
|
|
Move the current Intune-shaped subject-processing logic out of the core path in `CompareBaselineToTenantJob`, including:
|
|
|
|
- policy-type-specific normalizer selection
|
|
- section or evidence shaping that assumes Intune policy structure
|
|
- special-case subject handling such as RBAC role-definition compare rules
|
|
- strategy-owned subject projection metadata
|
|
|
|
Keep generic helpers such as `CurrentStateHashResolver`, `DriftHasher`, and finding lifecycle orchestration reusable by the job.
|
|
|
|
### 5. Feed existing finding and summary writers from the new result contract
|
|
|
|
Replace raw per-subject drift arrays with the structured compare-subject result contract where orchestration needs:
|
|
|
|
- summary aggregation
|
|
- finding write or update
|
|
- diagnostics persistence
|
|
- operator-safe degraded or failed state explanation
|
|
|
|
Do not create a new compare-result table.
|
|
|
|
### 6. Harden existing compare surfaces
|
|
|
|
Update the existing compare launch and review surfaces so they remain truthful for:
|
|
|
|
- unsupported scope
|
|
- mixed-strategy scope
|
|
- incomplete evidence
|
|
- ambiguous identity
|
|
- strategy failure
|
|
|
|
This work should stay within the existing baseline profile detail, compare matrix, tenant compare landing, and canonical run-detail surfaces.
|
|
|
|
## Focused Verification
|
|
|
|
Run the most relevant suites after each phase:
|
|
|
|
```bash
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineComparePreconditionsTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareExecutionGuardTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareFindingsTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareRbacRoleDefinitionsTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareMatrixPageTest.php
|
|
```
|
|
|
|
If the compare landing or matrix messaging changes materially, keep existing browser smoke coverage green as a final confidence pass.
|
|
|
|
## Final Validation
|
|
|
|
1. Run formatting:
|
|
|
|
```bash
|
|
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
|
|
```
|
|
|
|
2. Re-run the focused compare test pack.
|
|
3. Confirm that unsupported or mixed-scope compare requests fail before enqueue.
|
|
4. Confirm that the current Intune compare path still produces the same operator-visible finding, summary, and trust outcomes. |