houseplan-card/docs/AUDIT-QUALITY.md

Audit — implementation quality

Snapshot: 2026-08-05, product v1.58.0. Severity: critical / major / minor / nit. No critical RCE found under normal HA session auth.

1. Architecture snapshot

src/                         Lit 3 Lovelace cards (houseplan + space-card)
  houseplan-card.ts          ~8691 LOC — orchestration god-object
  logic.ts / devices.ts / …  extracted pure modules (good)
  styles.ts                  ~2223 LOC CSS-in-JS
custom_components/houseplan/ HA integration (storage, WS, HTTP, trails)
dist/ + frontend/            committed bundle (CI byte-compares)
demo/                        Playwright harness + smoke_*.mjs
tests_backend/               pure + HA-harness pytest

Bundle: ≈449 KB raw / ≈128 KB gzip — acceptable for a full editor+viewer.

2. What is strong

Backend

• Single write-auth helper (auth.may_write) with fail-closed when entry missing (audit B2 lesson documented in the module).
• Voluptuous validation with cross-language option-list tests that parse DISPLAY_MODES / TAP_ACTIONS from logic.ts — rare and valuable.
• Config CAS via expected_rev; plan COW + quotas; never-delete-on-inference file policy (SCOPE).
• Geometry migration with durable geom_pending intent (HP-1490 class).
• Content HTTP: requires_auth, signed URLs for <image href>, SVG CSP sandbox.
• Diagnostics / repairs / system_health present; quality_scale.yaml mostly honest (test-coverage, strict-typing, docs todos marked todo).

Frontend (extracted brain)

• Tap security model in resolveTapAction — locks/alarms never toggle from the plan; cover garage/door/gate guarded; run limited to automation/script/scene.
• Pure geometry / devices / sun / vacuum / resize / align-grid / signing modules with solid node:test coverage (~270 tests).
• Shared config-store + space-geometry/render for houseplan-space-card.
• Optimistic UI without rollback is documented intentional (ARCHITECTURE).

Process

• Four test layers + smoke policy (“[manual] must have a failing auto check”).
• Dual CHANGELOG (en/ru), SCOPE guard rail, CONTRIBUTING five-minute loop.
• CI: hacs + hassfest + frontend + backend + smoke job.

3. Findings (ranked)

#	Sev	Finding	Where
1	major	God-object card: ~8691 LOC, ~359 methods, ~125 private fields; render() ~382 lines. Smokes-only coverage for orchestration.	src/houseplan-card.ts
2	major	strict: true hollowed by noImplicitAny: false; ~200 any sites in the card alone; hass: any everywhere	tsconfig.json, card / devices / logic
3	major	Write-policy split: UI _canEdit is always admin-gated; API default admin_only=False lets any authenticated user write via WS/HTTP	houseplan-card.ts ≈L247–249, auth.py
4	major	_canEdit fails open when hass.user is missing (is_admin !== false)	card ≈L248
5	major	styles.ts ~2223 LOC — second maintainability sink; untested	src/styles.ts
6	minor	layout/update has no expected_rev — multi-tablet last-writer-wins per point	websocket_api.py
7	minor	Marker binding is bare str; ripple_color not hex-matched; decor w/h allow negatives via _NORM	validation.py
8	minor	Card-level tap_action / resolveTapAction cardDefault is dead / ignored — confusing API surface	types.ts, click path
9	minor	Store _async_migrate_func is a no-op; real migrations live ad-hoc in setup	store.py, __init__.py
10	nit	quality_scale.yaml cites test_config_flow.py; file is test_ha_config_flow.py	quality_scale.yaml
11	nit	Duplicated fireEvent / navigate in card + space-card	both files
—	positive	Forbidden-domain tap model + confirm + cover guards	logic.ts
—	positive	Signed content + SVG sandbox	http_api.py, signing.ts

No critical auth bypass of HA sessions found. Closest systemic issue is finding #3 (API openness vs UI) under the default options.

4. TypeScript & tooling

Item	State
tsc --noEmit in build	Yes — correct (rollup TS plugin can warn-and-ship)
ESLint / Prettier	Absent
noImplicitAny	Off
Frontend unit of the Lit class	None
mypy strict (backend)	quality_scale todo

5. Test map

Layer	What it proves	Gap
npm test (~270)	Pure logic, i18n parity, tap security, geometry	Not the card shell
pytest pure	validation.py without HA	—
HA-harness (py≥3.13)	setup, WS races, auth, upload, geometry repair	Coverage % unmeasured
demo/smoke_*.mjs (~100)	Real pointer/UI against fake hass	Pixel flakes (smoke_opening_measure); no Safari/Companion matrix

Human checklist in TESTING.md last full self-run recorded at v1.21.1 while product is at v1.58.0 — auto net grew; documented human pass did not.

6. Docs drift (quality of truth)

Doc	Drift
ARCHITECTURE.md intro	Still mentions old src/data/house.ts / 1489×1053 era in places; square/infinite canvas sections newer
UX-MODES.md header	Still says “No code has been changed yet” — Phase 11 shipped
PRODUCT.md competitor table	Stale — easy-floorplan 11→430★ (see AUDIT-MARKET)
STATUS.md	Generally current as of 2026-08-04

Docs discipline is a project strength; these drifts are fixable and should be treated as debt, not ignored.

7. Top 10 technical debt (actionable)

1. Split houseplan-card.ts into shell + Plan/Devices/Decor editors + dialogs.
2. Turn on noImplicitAny incrementally; type a thin Hass surface.
3. Align write policy: wire UI to admin_only, or default admin_only=True.
4. Fail closed on missing hass.user.
5. Add CAS / expected_rev to layout/update (or document single-writer assumption).
6. Split styles.ts by feature surface.
7. Tighten MARKER_SCHEMA (binding, colors, decor extents, space ids).
8. Unit-test orchestration hotspots (_clickDevice, write-chain conflicts, modes).
9. Real Store migrations or document setup-time migrations as the only path.
10. Remove or re-wire dead card-level tap_action / cardDefault.

Detailed priority and sequencing: AUDIT-RECOMMENDATIONS.md.

8. Quality-scale honesty check

Claim	Audit view
Bronze structural items done	Accurate
Silver unloading / owner done	Accurate
Gold diagnostics / repairs done	Accurate
test-coverage / strict-typing / docs examples todo	Accurate — keep them todo until measured
config-flow-test-coverage path typo	Nit — fix filename in yaml

Overall: self-assessment is trustworthy; do not mark coverage done without a number.