Skip to content

Commit 986bf42

Browse files
SimplicityGuySimplicityGuy
committed
chore: mdformat
1 parent 7f243de commit 986bf42

6 files changed

Lines changed: 103 additions & 52 deletions

‎api/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -466,10 +466,10 @@ Internal endpoints called by the Insights service over HTTP to fetch raw query r
466466

467467
### Health
468468

469-
| Method | Path | Port | Description |
470-
| ------ | --------- | ---- | ----------------------------------------------- |
471-
| GET | `/health` | 8004 | Health check on the main API server |
472-
| GET | `/health` | 8005 | Health check on the dedicated health server |
469+
| Method | Path | Port | Description |
470+
| ------ | --------- | ---- | ------------------------------------------- |
471+
| GET | `/health` | 8004 | Health check on the main API server |
472+
| GET | `/health` | 8005 | Health check on the dedicated health server |
473473

474474
## Development
475475

‎docs/admin-guide.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -57,14 +57,14 @@ Dead-letter queues (DLQs) collect messages that consumers failed to process. Eac
5757
| `discogsography-discogs-tableinator-labels.dlq` | Tableinator |
5858
| `discogsography-discogs-tableinator-masters.dlq` | Tableinator |
5959
| `discogsography-discogs-tableinator-releases.dlq` | Tableinator |
60-
| `discogsography-musicbrainz-brainzgraphinator-artists.dlq` | Brainzgraphinator |
61-
| `discogsography-musicbrainz-brainzgraphinator-labels.dlq` | Brainzgraphinator |
60+
| `discogsography-musicbrainz-brainzgraphinator-artists.dlq` | Brainzgraphinator |
61+
| `discogsography-musicbrainz-brainzgraphinator-labels.dlq` | Brainzgraphinator |
6262
| `discogsography-musicbrainz-brainzgraphinator-release-groups.dlq` | Brainzgraphinator |
63-
| `discogsography-musicbrainz-brainzgraphinator-releases.dlq` | Brainzgraphinator |
64-
| `discogsography-musicbrainz-brainztableinator-artists.dlq` | Brainztableinator |
65-
| `discogsography-musicbrainz-brainztableinator-labels.dlq` | Brainztableinator |
63+
| `discogsography-musicbrainz-brainzgraphinator-releases.dlq` | Brainzgraphinator |
64+
| `discogsography-musicbrainz-brainztableinator-artists.dlq` | Brainztableinator |
65+
| `discogsography-musicbrainz-brainztableinator-labels.dlq` | Brainztableinator |
6666
| `discogsography-musicbrainz-brainztableinator-release-groups.dlq` | Brainztableinator |
67-
| `discogsography-musicbrainz-brainztableinator-releases.dlq` | Brainztableinator |
67+
| `discogsography-musicbrainz-brainztableinator-releases.dlq` | Brainztableinator |
6868

6969
**Purging** permanently deletes all messages in a DLQ. Do this when:
7070

‎docs/superpowers/plans/2026-04-03-extraction-analysis-dashboard.md‎

Lines changed: 51 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -10,28 +10,30 @@
1010

1111
**Spec:** `docs/superpowers/specs/2026-04-03-extraction-analysis-dashboard-design.md`
1212

13-
---
13+
______________________________________________________________________
1414

1515
## File Structure
1616

17-
| Action | File | Responsibility |
18-
|--------|------|----------------|
19-
| Create | `api/routers/extraction_analysis.py` | All 7 API endpoints under `/api/admin/extraction-analysis/` |
20-
| Create | `tests/api/test_extraction_analysis.py` | API endpoint tests with mock filesystem |
21-
| Modify | `api/api.py:39,258,399` | Import, configure, and register the new router |
22-
| Modify | `docker-compose.yml:263-264` | Add read-only data volume mounts to API service |
23-
| Modify | `docker-compose.prod.yml:186+` | Add read-only data volume mounts to API (prod) |
24-
| Modify | `dashboard/admin_proxy.py:30,352` | Add path regex with dots + 7 new proxy routes |
25-
| Modify | `dashboard/static/admin.html:282,773` | Add tab button + tab panel HTML |
26-
| Modify | `dashboard/static/admin.js:229,247,1454` | Add tab switching + all fetch/render methods |
27-
| Create | `tests/dashboard/test_extraction_analysis_proxy.py` | Dashboard proxy route tests |
17+
| Action | File | Responsibility |
18+
| ------ | --------------------------------------------------- | ----------------------------------------------------------- |
19+
| Create | `api/routers/extraction_analysis.py` | All 7 API endpoints under `/api/admin/extraction-analysis/` |
20+
| Create | `tests/api/test_extraction_analysis.py` | API endpoint tests with mock filesystem |
21+
| Modify | `api/api.py:39,258,399` | Import, configure, and register the new router |
22+
| Modify | `docker-compose.yml:263-264` | Add read-only data volume mounts to API service |
23+
| Modify | `docker-compose.prod.yml:186+` | Add read-only data volume mounts to API (prod) |
24+
| Modify | `dashboard/admin_proxy.py:30,352` | Add path regex with dots + 7 new proxy routes |
25+
| Modify | `dashboard/static/admin.html:282,773` | Add tab button + tab panel HTML |
26+
| Modify | `dashboard/static/admin.js:229,247,1454` | Add tab switching + all fetch/render methods |
27+
| Create | `tests/dashboard/test_extraction_analysis_proxy.py` | Dashboard proxy route tests |
2828

29-
---
29+
______________________________________________________________________
3030

3131
### Task 1: Docker Compose Volume Mounts
3232

3333
**Files:**
34+
3435
- Modify: `docker-compose.yml:263-264`
36+
3537
- Modify: `docker-compose.prod.yml:186+`
3638

3739
- [ ] **Step 1: Add data volumes to API service in docker-compose.yml**
@@ -70,12 +72,14 @@ git add docker-compose.yml docker-compose.prod.yml
7072
git commit -m "feat: mount discogs/musicbrainz data volumes on API service (read-only)"
7173
```
7274

73-
---
75+
______________________________________________________________________
7476

7577
### Task 2: API Router — Versions Endpoint
7678

7779
**Files:**
80+
7881
- Create: `api/routers/extraction_analysis.py`
82+
7983
- Create: `tests/api/test_extraction_analysis.py`
8084

8185
- [ ] **Step 1: Write tests for the versions endpoint**
@@ -262,11 +266,13 @@ async def list_versions(
262266
- [ ] **Step 4: Register the router in api/api.py**
263267

264268
Add import at line 39 (with the other router imports):
269+
265270
```python
266271
import api.routers.extraction_analysis as _extraction_analysis_router
267272
```
268273

269274
Add configure call around line 258 (with the other configure calls):
275+
270276
```python
271277
_extraction_analysis_router.configure(
272278
discogs_root=os.environ.get("DISCOGS_DATA_ROOT"),
@@ -275,6 +281,7 @@ _extraction_analysis_router.configure(
275281
```
276282

277283
Add router inclusion around line 403 (with the other include_router calls):
284+
278285
```python
279286
app.include_router(_extraction_analysis_router.router)
280287
```
@@ -291,12 +298,14 @@ git add api/routers/extraction_analysis.py tests/api/test_extraction_analysis.py
291298
git commit -m "feat: add extraction analysis versions endpoint"
292299
```
293300

294-
---
301+
______________________________________________________________________
295302

296303
### Task 3: API Router — Summary Endpoint
297304

298305
**Files:**
306+
299307
- Modify: `api/routers/extraction_analysis.py`
308+
300309
- Modify: `tests/api/test_extraction_analysis.py`
301310

302311
- [ ] **Step 1: Write tests for the summary endpoint**
@@ -544,12 +553,14 @@ git add api/routers/extraction_analysis.py tests/api/test_extraction_analysis.py
544553
git commit -m "feat: add extraction analysis summary endpoint"
545554
```
546555

547-
---
556+
______________________________________________________________________
548557

549558
### Task 4: API Router — Violations Endpoints (List + Detail)
550559

551560
**Files:**
561+
552562
- Modify: `api/routers/extraction_analysis.py`
563+
553564
- Modify: `tests/api/test_extraction_analysis.py`
554565

555566
- [ ] **Step 1: Write tests for violations list and detail**
@@ -809,12 +820,14 @@ git add api/routers/extraction_analysis.py tests/api/test_extraction_analysis.py
809820
git commit -m "feat: add violations list and detail endpoints"
810821
```
811822

812-
---
823+
______________________________________________________________________
813824

814825
### Task 5: API Router — Parsing Errors Endpoint
815826

816827
**Files:**
828+
817829
- Modify: `api/routers/extraction_analysis.py`
830+
818831
- Modify: `tests/api/test_extraction_analysis.py`
819832

820833
- [ ] **Step 1: Write tests for parsing error detection**
@@ -1080,12 +1093,14 @@ git add api/routers/extraction_analysis.py tests/api/test_extraction_analysis.py
10801093
git commit -m "feat: add parsing error detection endpoint with XML vs JSON comparison"
10811094
```
10821095

1083-
---
1096+
______________________________________________________________________
10841097

10851098
### Task 6: API Router — Compare and Prompt Context Endpoints
10861099

10871100
**Files:**
1101+
10881102
- Modify: `api/routers/extraction_analysis.py`
1103+
10891104
- Modify: `tests/api/test_extraction_analysis.py`
10901105

10911106
- [ ] **Step 1: Write tests for compare endpoint**
@@ -1395,12 +1410,14 @@ git add api/routers/extraction_analysis.py tests/api/test_extraction_analysis.py
13951410
git commit -m "feat: add version comparison and prompt context endpoints"
13961411
```
13971412

1398-
---
1413+
______________________________________________________________________
13991414

14001415
### Task 7: Dashboard Proxy Routes
14011416

14021417
**Files:**
1418+
14031419
- Modify: `dashboard/admin_proxy.py`
1420+
14041421
- Create: `tests/dashboard/test_extraction_analysis_proxy.py`
14051422

14061423
- [ ] **Step 1: Write tests for proxy routes**
@@ -1694,11 +1711,12 @@ git add dashboard/admin_proxy.py tests/dashboard/test_extraction_analysis_proxy.
16941711
git commit -m "feat: add extraction analysis proxy routes to dashboard"
16951712
```
16961713

1697-
---
1714+
______________________________________________________________________
16981715

16991716
### Task 8: Dashboard UI — Tab Button and Panel HTML
17001717

17011718
**Files:**
1719+
17021720
- Modify: `dashboard/static/admin.html`
17031721

17041722
- [ ] **Step 1: Add the tab button**
@@ -1866,11 +1884,12 @@ git add dashboard/static/admin.html
18661884
git commit -m "feat: add extraction analysis tab HTML to admin dashboard"
18671885
```
18681886

1869-
---
1887+
______________________________________________________________________
18701888

18711889
### Task 9: Dashboard UI — JavaScript Logic
18721890

18731891
**Files:**
1892+
18741893
- Modify: `dashboard/static/admin.js`
18751894

18761895
This task adds all the JavaScript methods for the extraction analysis tab. **Security note:** All dynamic content from API responses that is inserted into the DOM must be HTML-escaped to prevent XSS. Use `textContent` for plain text and an escape helper for any HTML templates.
@@ -1893,15 +1912,19 @@ function _esc(str) {
18931912
In `admin.js`, update the `switchTab()` method (line 229):
18941913

18951914
Change:
1915+
18961916
```javascript
18971917
const panels = ['extractions', 'dlq', 'users', 'storage', 'queue-trends', 'system-health', 'audit-log'];
18981918
```
1919+
18991920
To:
1921+
19001922
```javascript
19011923
const panels = ['extractions', 'dlq', 'users', 'storage', 'queue-trends', 'system-health', 'audit-log', 'extraction-analysis'];
19021924
```
19031925

19041926
Add after the `audit-log` fetch block (line 246):
1927+
19051928
```javascript
19061929
} else if (tabName === 'extraction-analysis') {
19071930
this.fetchExtractionAnalysisVersions();
@@ -1911,13 +1934,15 @@ Add after the `audit-log` fetch block (line 246):
19111934
- [ ] **Step 3: Add constructor state and event bindings**
19121935

19131936
In the constructor (around line 32-47), add state properties:
1937+
19141938
```javascript
19151939
this._eaVersions = [];
19161940
this._eaSelectedRecords = new Map();
19171941
this._eaParsingErrors = null;
19181942
```
19191943

19201944
In the `bindEvents()` method, add event bindings for the extraction analysis tab:
1945+
19211946
```javascript
19221947
// Extraction Analysis sub-view switching
19231948
document.querySelectorAll('.ea-view-btn').forEach(btn => {
@@ -1945,7 +1970,7 @@ In the `bindEvents()` method, add event bindings for the extraction analysis tab
19451970

19461971
Before the closing `}` of the `AdminDashboard` class (line 1454), add all methods. Use `_esc()` for all values inserted via innerHTML, and `textContent` for plain text values:
19471972

1948-
```javascript
1973+
````javascript
19491974
// ─── Extraction Analysis ─────────────────────────────────────────────
19501975

19511976
_eaSwitchView(viewName) {
@@ -2409,7 +2434,7 @@ Before the closing `}` of the `AdminDashboard` class (line 1454), add all method
24092434
textarea.select();
24102435
}
24112436
}
2412-
```
2437+
````
24132438

24142439
- [ ] **Step 5: Commit**
24152440

@@ -2418,11 +2443,12 @@ git add dashboard/static/admin.js dashboard/static/admin.html
24182443
git commit -m "feat: add extraction analysis JavaScript logic to admin dashboard"
24192444
```
24202445

2421-
---
2446+
______________________________________________________________________
24222447

24232448
### Task 10: Integration Verification
24242449

24252450
**Files:**
2451+
24262452
- All modified files
24272453

24282454
- [ ] **Step 1: Run full API test suite**
@@ -2453,6 +2479,7 @@ Expected: No output (success)
24532479
- [ ] **Step 6: Commit any fixes**
24542480

24552481
If any fixes were needed, commit them:
2482+
24562483
```bash
24572484
git add -A
24582485
git commit -m "fix: resolve integration issues from extraction analysis feature"

‎docs/superpowers/plans/2026-04-03-extractor-mutual-exclusion.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,25 +10,29 @@
1010

1111
**Spec:** `docs/superpowers/specs/2026-04-03-extractor-mutual-exclusion-design.md`
1212

13-
---
13+
______________________________________________________________________
1414

1515
### File Map
1616

17-
| File | Action | Responsibility |
18-
|------|--------|---------------|
19-
| `extractor/src/config.rs` | Modify | Add `discogs_health_url` field |
20-
| `extractor/src/extractor.rs` | Modify | Add `wait_for_discogs_idle()`, call it from `run_musicbrainz_loop()` |
21-
| `extractor/src/tests/config_tests.rs` | Modify | Test new config field |
22-
| `extractor/src/tests/extractor_tests.rs` | Modify | Tests for `wait_for_discogs_idle()` |
17+
| File | Action | Responsibility |
18+
| ---------------------------------------- | ------ | -------------------------------------------------------------------- |
19+
| `extractor/src/config.rs` | Modify | Add `discogs_health_url` field |
20+
| `extractor/src/extractor.rs` | Modify | Add `wait_for_discogs_idle()`, call it from `run_musicbrainz_loop()` |
21+
| `extractor/src/tests/config_tests.rs` | Modify | Test new config field |
22+
| `extractor/src/tests/extractor_tests.rs` | Modify | Tests for `wait_for_discogs_idle()` |
2323

24-
---
24+
______________________________________________________________________
2525

2626
### Task 1: Add `discogs_health_url` to config
2727

2828
**Files:**
29+
2930
- Modify: `extractor/src/config.rs:7-23` (struct definition)
31+
3032
- Modify: `extractor/src/config.rs:25-44` (Default impl)
33+
3134
- Modify: `extractor/src/config.rs:66-124` (from_env)
35+
3236
- Test: `extractor/src/tests/config_tests.rs`
3337

3438
- [ ] **Step 1: Write the failing test**
@@ -92,12 +96,14 @@ git add extractor/src/config.rs extractor/src/tests/config_tests.rs
9296
git commit -m "feat(extractor): add discogs_health_url config field"
9397
```
9498

95-
---
99+
______________________________________________________________________
96100

97101
### Task 2: Implement `wait_for_discogs_idle()`
98102

99103
**Files:**
104+
100105
- Modify: `extractor/src/extractor.rs` — add the new function
106+
101107
- Test: `extractor/src/tests/extractor_tests.rs`
102108

103109
- [ ] **Step 1: Write the failing tests**
@@ -344,11 +350,12 @@ git add extractor/src/extractor.rs extractor/src/tests/extractor_tests.rs extrac
344350
git commit -m "feat(extractor): add wait_for_discogs_idle() with health polling"
345351
```
346352

347-
---
353+
______________________________________________________________________
348354

349355
### Task 3: Integrate into `run_musicbrainz_loop()`
350356

351357
**Files:**
358+
352359
- Modify: `extractor/src/extractor.rs:800-879` — add calls before each `process_musicbrainz_data()`
353360

354361
- [ ] **Step 1: Add wait call before initial extraction**
@@ -413,7 +420,7 @@ git add extractor/src/extractor.rs
413420
git commit -m "feat(extractor): integrate Discogs health check into MusicBrainz loop"
414421
```
415422

416-
---
423+
______________________________________________________________________
417424

418425
### Task 4: Final verification
419426

0 commit comments

Comments
 (0)