azaion/ui
1
0
Fork 0
mirror of https://github.com/azaion/ui.git synced 2026-06-21 14:41:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-447] autodev Steps 1-4 baseline: docs, tests, refactor specs

Browse Source 
Captures the full output of autodev existing-code Phase A through
Step 4 (Code Testability Revision) for the Azaion UI workspace:

- Step 1 Document: _docs/02_document/ (FINAL_report, architecture,
  glossary, components/, modules/, diagrams/, system-flows,
  module-layout) plus _docs/00_problem/ + _docs/01_solution/ +
  _docs/legacy/ + _docs/how_to_test + README.
- Step 2 Architecture Baseline: architecture_compliance_baseline.md.
- Step 3 Test Spec: _docs/02_document/tests/ (environment,
  test-data, blackbox/performance/resilience/security/
  resource-limit tests, traceability-matrix), enum_spec_snapshot,
  expected_results/results_report.md (98 rows), plus the
  run-tests.sh + run-performance-tests.sh runners.
- Step 4 Code Testability Revision: 01-testability-refactoring/
  run dir (list-of-changes C01-C07, deferred_to_refactor,
  analysis/research_findings + refactoring_roadmap) and the 7
  child task specs AZ-448..AZ-454 under _docs/02_tasks/todo/
  plus _dependencies_table.md.
- _docs/_autodev_state.md pins the cursor at Step 4 / refactor
  Phase 4 entry so /autodev resumes cleanly.

Epic AZ-447 (UI testability gates) tracks the 7 child tasks that
will land in subsequent commits.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-11 00:38:49 +03:00
parent da0a5aa187
commit 510df68bcf
84 changed files with 13065 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/04_refactoring/01-testability-refactoring/analysis/refactoring_roadmap.md
+57
View File
@@ -0,0 +1,57 @@
# Refactoring Roadmap — 01-testability-refactoring
**Date**: 2026-05-10
**Run name**: 01-testability-refactoring
**Epic**: AZ-447
## Weak points assessment
| Location | Description | Impact | Proposed solution | Status |
|----------|-------------|--------|-------------------|--------|
| `src/features/flights/flightPlanUtils.ts:60` | Hardcoded OpenWeatherMap key + endpoint | NFT-SEC-09 fails; e2e cannot stub OWM | C01 (AZ-448) + C02 (AZ-449) | Selected |
| `src/features/flights/types.ts:56-57` | Hardcoded tile URLs (OSM + Esri) | AC-N3 / NFT-RES-03 fail; air-gap broken | C03 (AZ-450) | Selected |
| `src/features/flights/mapIcons.ts:18` | External `unpkg.com` marker icon URL | Air-gap broken; version mismatch with pinned Leaflet | C04 (AZ-451) | Selected |
| `src/api/client.ts` request prefix | No override hook for `/api/...` | E2E flexibility blocked | C05 (AZ-452) | Selected |
| `src/api/client.ts:34` login redirect | Direct `window.location.href` mutation | Tests cannot easily verify the call | C06 (AZ-453) | Selected |
| `src/api/client.ts:1-9` token accessor | Intentional but undocumented | Risks accidental dead-code deletion | C07 (AZ-454) | Selected |
## Gap analysis (what's missing — and what we are NOT fixing in this run)
Items considered out of scope for the testability run and deferred to Step 8 (Refactor) or Phase B feature cycle — see `_docs/04_refactoring/01-testability-refactoring/deferred_to_refactor.md` for the full list. Highlights:
- D01 — Bootstrap `credentials:'include'` (FT-P-01 quarantine): wire-contract product fix.
- D02 — Numeric enum drift in `src/types/index.ts` (FT-P-04/05/06): cross-service wire-contract change.
- D03–D12 — Missing UX / features.
- D13 — Parent-suite docs stale (parent-repo concern; record as leftover).
## Phased roadmap
**Phase 1 — Critical fixes (this run)**
| Phase | Tasks | Why now |
|-------|-------|---------|
| 1a (quick wins) | AZ-451 (marker icon), AZ-454 (JSDoc) | Smallest blast radius; trivial verification |
| 1b (tied pair) | AZ-448 + AZ-449 (same file) | Lands together to keep the file's mid-state coherent |
| 1c (independent low-risk) | AZ-450 (tile URLs), AZ-452 (getApiBase), AZ-453 (navigateToLogin) | Any order; each touches one file independently |
**Phase 2 — Major improvements**: none in this run. Phase B will pick up deferred items D01–D12.
**Phase 3 — Enhancements**: none in this run.
## Selected hardening tracks
User has not opted into Tech Debt / Performance / Security tracks at this stage — testability is the explicit scope of Step 4 per `flows/existing-code.md`. The autodev will offer the hardening-tracks Choose block at Phase 2 of the refactor skill if applicable; for this run the answer is **E) None — proceed with structural refactoring only** (testability changes are structural; hardening would expand scope).
## Applicability gate (per-item)
| Roadmap item | Constraint fit | Mismatches | Required evidence | Status |
|--------------|---------------|------------|-------------------|--------|
| C01 | AC-O6, NFT-SEC-09, S3 | None | `package.json` pins `vite ^6.2.0` | Selected |
| C02 | E10, S3 | None | Same | Selected |
| C03 | AC-N3, E1, S9 | None | `leaflet ^1.9.4` + `react-leaflet ^5` API surface unchanged | Selected |
| C04 | AC-N3, E1, S9 | None | `node_modules/leaflet/dist/images/marker-icon.png` exists | Selected |
| C05 | AC-O3, AC-23, E2 | None | Default `''` preserves all relative call sites | Selected |
| C06 | AC-23 | None | Same shape as existing `setToken` pattern | Selected |
| C07 | AC-02; coderule.mdc | None | Comment-only — zero behavioral change | Selected |
All 7 items pass the gate. No items marked Rejected / Experimental only / Needs user decision.
_docs/04_refactoring/01-testability-refactoring/analysis/research_findings.md
+54
View File
@@ -0,0 +1,54 @@
# Research Findings — 01-testability-refactoring
**Date**: 2026-05-10
**Mode**: guided (testability run)
## Current state analysis
| Concern | Current pattern | Strength | Weakness |
|---------|----------------|----------|----------|
| External API credentials | Literal string in `flightPlanUtils.ts:60` | Simple to read | Violates AC-O6; blocks NFT-SEC-09; prevents stub interception |
| External endpoint base URLs | Hardcoded in source (`flightPlanUtils.ts`, `types.ts`, `mapIcons.ts`) | None | Cannot be overridden for tests; breaks air-gap; couples to specific CDN versions |
| API request prefix | Implicit `/api/...` relative paths | Works on production where SPA + suite share nginx | No override hook for tests or alternative deployments |
| Module-level access token | `setToken / getToken` accessor on a module-scope `let accessToken` | Already a thin accessor (good!) | Undocumented intent; reads as dead code |
| Login redirect after failed refresh | Direct `window.location.href = '/login'` | Works in production | Hard to verify in tests without globally stubbing `window.location` |
## Alternative approaches considered
No library replacements are required for this run. Every change uses primitives already in the project:
1. **Vite env vars (`import.meta.env.VITE_*`)** — built-in to Vite 6 (S3). No new dependency. Verification: Vite docs are the project's pinned reference at `/vite-pwa` (n/a) — `vite-env.d.ts` already exists in the project, confirming the pattern is established.
2. **Module-level setter pattern for `setNavigateToLogin`** — same shape as the existing `setToken` accessor. No library evaluation needed.
3. **Vite asset import for marker PNG** — `import x from './path.png'` works out of the box with Vite's default asset pipeline. The `leaflet` package already ships the file at `dist/images/marker-icon.png`. No new dependency.
Because no library/SDK/framework is being added or replaced, the per-mode API capability verification protocol in `refactor/phases/02-analysis.md` (steps 1–5) **does not apply** to this run. The MVE evidence requirement is N/A — every change reuses an existing project capability.
## Constraint-fit table
| Change ID | Pinned mode/config | Constraints checked | Evidence | Mismatches | Status |
|-----------|-------------------|---------------------|----------|------------|--------|
| C01 (AZ-448) | `import.meta.env.VITE_OWM_API_KEY`, read at call time | AC-O6, NFT-SEC-09, S3 (Vite 6) | `package.json` pins `vite ^6.2.0`; `import.meta.env` is built-in; project does not yet use Vite env vars — this run introduces the pattern | None | Selected |
| C02 (AZ-449) | `import.meta.env.VITE_OWM_BASE_URL`, default-fallback | Same as C01 + E10 (OWM direct-from-browser today) | Same | None | Selected |
| C03 (AZ-450) | Two env vars with computed-at-module-load defaults | AC-N3, NFT-RES-03, E1, S9 (Leaflet 1.9.4) | `package.json` pins `leaflet ^1.9.4`, `react-leaflet ^5.0.0`; tile URL is consumed as a string by `TileLayer` — no Leaflet API change | None | Selected |
| C04 (AZ-451) | `import markerIcon from 'leaflet/dist/images/marker-icon.png'` | AC-N3, E1, S9 | `leaflet@^1.9.4` ships the PNG at that path (verified by reading `node_modules/leaflet/dist/images/`) | None | Selected |
| C05 (AZ-452) | Function returning `import.meta.env.VITE_API_BASE_URL ?? ''` | AC-O3, AC-23, E2 (nginx prefix-stripping) | Default `''` preserves every relative call site; nginx behavior outside the SPA — unchanged | None | Selected |
| C06 (AZ-453) | Module-level mutable function + setter | AC-23 (refresh transparency) | Same shape as existing `setToken` | None | Selected |
| C07 (AZ-454) | JSDoc only | AC-02 (no bearer storage); `coderule.mdc` dead-code rule | Comment-only | None | Selected |
## Prioritized recommendations
- **Quick wins** (land first): C04 (single-line file edit), C07 (comment-only).
- **Tied pair**: C01 + C02 — same file, land in one commit.
- **Independent low-risk**: C03, C05, C06 — can land in any order.
## References
This run did not require `context7` lookups (no library replacement). Internal references used:
- `_docs/00_problem/restrictions.md` (E1, E2, E10, S3, S9, O3, O6)
- `_docs/00_problem/acceptance_criteria.md` (AC-N3, AC-O6, AC-23)
- `_docs/02_document/tests/blackbox-tests.md` (FT-N* references)
- `_docs/02_document/tests/security-tests.md` (NFT-SEC-09 traceability)
- `_docs/02_document/tests/resilience-tests.md` (NFT-RES-03 traceability)
- `_docs/02_document/tests/traceability-matrix.md`
- Vite 6 documentation: built-in `import.meta.env` (project-pinned via `package.json`).